A thesis notebook based on TiddlyWiki.
This is an example of a thesis notebook powered by TiddlyWiki 5.0.8-beta.
TiddlyWiki is a great piece of software created by Jeremy Ruston. It allows you, among other things, to take notes, organize ideas, store information, and display all your stuff the way you want. It is an incredibly flexible tool you can adapt to fit almost all your needs.
This TiddlyWiki has been customized to serve as a philosophy notebook centered around authors, books and papers, concepts and theories, and personal notes. I use it along with Zotero, which is a dedicated bibliography software. Both are free, open source projects. TiddlyWiki can be downloaded at http://tiddlywiki.com.
buggyj has created several useful plugins, including a WYSIWYG HTML editor, a configurable calendar and tag lists with draggable ordering.
A collection of customisations and macros from Danielo Rodriguez.
This is my personal tiddlywiki file for testing.
Here I will post the tools and Macros that I develop for this awesome tool. That way, all the help the comunity gave me can came back to the comunity again.
A guide to creating a baby journal with TiddlyWiki.
Keeping a journal about your baby is fun. It allows you to keep track of those events in your baby's life and development that are most important to you, and to tell them in your own words. [...]
There are plenty of online services that can help to keep such a diary, but you need to have an internet connection to access them, and you have to trust them to keep your data safe.
A step by step guide to running TiddlyWiki on a CentOS Virtual Private Server.
In this tutorial we will guide you through the steps of installing and running TiddlyWiki on a CentOS 6 VPS.
We will also install and configure Nginx as a reverse proxy, so you can run TiddlyWiki behind Nginx.
A gamers guide to using TiddlyWiki.
I’ve been using TiddlyWiki for this game mainly to record the monsters’ locations and the items that they drop. This is so that when I need a certain item to upgrade/create weapons, I can quickly look it up; which monsters drop it and which quests have those monsters.
As I play the game, as I encounter new information, I just input them into my Shining Ark TiddlyWiki. It’s like I’m building a wiki from scratch. The reason why I don’t just use online wikis is that 1) it’s too easy to get spoiled and 2) sometimes online wikis provide too much information (who cares about the non-gameplay related descriptions that can be found in the game, etc).
Reaction to TiddlyWiki5 from the translator of the German edition of TiddlyWikiClassic.
There is little software that can still inspire me so even after years, as on the first day. This includes TiddlyWiki, the "pocket-wiki". The latter is because the Wiki completely fits into an HTML file, and this HTML file brings everything - JavaScript program logic, CSS appearance and the entire Wiki content as stored records. So a TiddlyWiki file is then sometimes happy times some megabytes in size, but just has the unbeatable advantage that it works just as fast file created locally in a variety of browsers.
(Translation from German by Google Translate)
A beautifully presented timeline widget using vis.js (http://visjs.org).
Source: https://github.com/emkayonline/tw5visjs
This plug-in allows TW5 to display tiddlers using the vis.js graphical timeline and graph widgets.
This plug-in has been testing on OS X with Safari, Chrome and Firefox, but should work under all operating systems and browser supported by TW5 and vis.js.
Also, the plug-in has been designed to work off-line, enabling it to be used without a wireless connection on an iPad/iPhone using TWEdit
Notes and tips by a developer working on writing TiddlyWiki plugins – including TWExe, a widget for running Windows scripts and executables.
A collection of articles covering integration with Fargo, Font Awesome and Google Calendar, and tips for managing task lists.
I have become a regular user of TiddlyWiki and have become so accustomed to using Font Awesome icons in Fargo that I wanted to incorporate the icons into my wikis as well.
A translation of the tiddlywiki.com documentation from Bram Chen, TiddlyWiki's Chinese translator.
Chris Hunt's detailed developer tutorials for getting started with writing widgets for TiddlyWiki.
These pages document aspects TiddlyWiki5 programming, sharing "lessons learned" to help developers to get started with TiddlyWiki5 customization and extension.
There are currently two articles in this wiki:
- A Simple Widget
- A More Complex Widget
Huge collection of customisations and tweaks from Ton Gerner.
I am a longtime user of TiddlyWiki Classic and still use it daily since you can't do everything in TiddlyWiki 5 (yet) ;)
I started experimenting with TW5 at the end of September 2013 (alpha10). Since I missed a few things in the layout I got used to in TiddlyWiki Classic 1, I started with modifying the layout of TW5. To share my knowledge, I made a few guides about these 'modifications'. The guides started as a non-linear personal web notebook (yeah, the subtitle of TiddlyWiki!). I started experimenting with layout things and used TW5 to document my experiments.
Stephan Hradek's growing catalogue of tips and tutorials. Stephan has also developed several plugins and macros that you can find at http://tiddlystuff.tiddlyspot.com/.
Some things in TiddlyWiki seem like Magic. As my preferred nick is Skeeve, I felt that TW5 Magick is a proper name for this collection of some of the "magic" tricks one can do with TiddlyWiki.
Dave Gifford's growing catalogue of tips and tutorials.
TiddlyWiki 5 is a great tool for note-taking, bookmarking, blogging, organizing to do lists, writing books, and more. But many of the things that can be done in TiddlyWiki 5 are often hidden to the new user, either because the user doesn't know about it or because the user doesn't know how to do it. TW5 mall is a modest catalog of hacks where you can discover new tricks in TiddlyWiki 5 and also find out in layman's terms how to implement them.
Tips and guides for using TiddlyWiki.
I never used Node.js until a couple weeks ago when I wanted to try a TW5 installation on Node and expand my knowledge a bit. I figured someone else may be in the same boat so I wrote it all down
A collection of TiddlyWiki resources from Mario Pietsch, with a focus on cloud deployments. Mario also maintains the German translation of TiddlyWiki.
My name is Mario Pietsch from Austria. I'm living near Salzburg.
This page, will be the portal to my TiddlyWiki, TiddlyWeb related content.
Matabele's stylish and clean system for personal task management.
This is my work in progress version of TW5, incorporating various features and ideas as and when they intrigue me. To grab any feature you may wish to try, drag the listed tiddlers across to the dropzone of an empty TiddlyWiki 5.0.10-beta
TiddlyWiki5 wouldn't be possible without the ongoing support of the TiddlyWiki user and developer community. Their attention and feedback has made it possible to gain an understanding of what is wanted from the product, and their passion for it has taught me that it is worth the investment that I am making.
TiddlyWiki5 stands on the shoulders of giants by incorporating code from these fine OpenSource projects:
Here's a macro that provides a Twitter Follow button for a particular username:
\define twitterFollowButton(username)
<iframe allowtransparency="true" frameborder="0" scrolling="no" src="//platform.twitter.com/widgets/follow_button.html?screen_name=$username$" style="width:300px; height:20px;"></iframe>
\endThe only change from the version published at https://dev.twitter.com/docs/follow-button is that new lines have been removed.
Note that the src URL is given without a protocol (ie "http" or "https"). It's done this way so that it works on sites whether they are hosted on a HTTP or HTTPS domain. If you want the Twitter button to work while using a TiddlyWiki offline on a "file://" URL, then you'll need to manually add the protocol. For example:
<iframe allowtransparency="true" frameborder="0" scrolling="no" src="http://platform.twitter.com/widgets/follow_button.html?screen_name=jermolene" style="width:300px; height:20px;"></iframe>Alerts are displayed as yellow boxes overlaying the main TiddlyWiki window. Each one corresponds to a tiddler with the tag $:/tags/Alert. Clicking the delete icon on an alert deletes the corresponding tiddler.
Here's a demo .
Alert tiddlers should have the following fields:
| Field | Description |
|---|---|
| title | By default, alert titles have the prefix $:/temp/alerts/ |
| text | The text of the alert message |
| modified | Date of the alert (used for ordering the alerts on screen) |
| component | Component name associated with the alert |
| tags | Must include $:/tags/Alert |
Current tiddlers:
Submit new entries to this collection of articles via GitHub, Twitter or by posting in the TiddlyWiki Groups.
A step by step guide to running TiddlyWiki on a CentOS Virtual Private Server.
In this tutorial we will guide you through the steps of installing and running TiddlyWiki on a CentOS 6 VPS.
We will also install and configure Nginx as a reverse proxy, so you can run TiddlyWiki behind Nginx.
A guide to creating a baby journal with TiddlyWiki.
Keeping a journal about your baby is fun. It allows you to keep track of those events in your baby's life and development that are most important to you, and to tell them in your own words. [...]
There are plenty of online services that can help to keep such a diary, but you need to have an internet connection to access them, and you have to trust them to keep your data safe.
Reaction to TiddlyWiki5 from the translator of the German edition of TiddlyWikiClassic.
There is little software that can still inspire me so even after years, as on the first day. This includes TiddlyWiki, the "pocket-wiki". The latter is because the Wiki completely fits into an HTML file, and this HTML file brings everything - JavaScript program logic, CSS appearance and the entire Wiki content as stored records. So a TiddlyWiki file is then sometimes happy times some megabytes in size, but just has the unbeatable advantage that it works just as fast file created locally in a variety of browsers.
(Translation from German by Google Translate)
An introduction to TiddlyWiki in Japanese.
A gamers guide to using TiddlyWiki.
I’ve been using TiddlyWiki for this game mainly to record the monsters’ locations and the items that they drop. This is so that when I need a certain item to upgrade/create weapons, I can quickly look it up; which monsters drop it and which quests have those monsters.
As I play the game, as I encounter new information, I just input them into my Shining Ark TiddlyWiki. It’s like I’m building a wiki from scratch. The reason why I don’t just use online wikis is that 1) it’s too easy to get spoiled and 2) sometimes online wikis provide too much information (who cares about the non-gameplay related descriptions that can be found in the game, etc).
If there is a SaverModule available that supports it, TiddlyWiki will automatically trigger a save of the current document on clicking tick or delete when editing a tiddler.
You should see a yellow notification at the top right of the window to confirm that an automatic save has taken place.
Automatic saving can be enabled or disabled through the Saving tab of the control panel. Behind the scenes, it is controlled through the configuration tiddler $:/config/AutoSave, which must have the value yes to enable automatic saving.
There are two ways to produce HTML block quotes in TiddlyWiki5, one for content spread across multiple lines, and one for single line content.
The syntax for multi-line block quotes is:
A citation can be added to the quote like this:
CSS classes can be added to a block quote:
The single-line syntax for block quotes is actually an extension of the syntax for Lists in WikiText. For example:
You can also nest quotes like this:
> A top quote
>> A subquote
> Another top quoteWhich renders as:
A top quote
A subquote
Another top quote
You can also mix block quotes with other list items. For example:
At its heart, TiddlyWiki5 is a relatively small boot kernel that runs either under Node.js or in the browser with all other functionality added via dynamically loaded modules.
The kernel boots just enough of the TiddlyWiki environment to allow it to load and execute module tiddlers. The module system is compatible with CommonJS and Node.js.
There are many different types of module: parsers, deserializers, widgets etc. It goes much further than you might expect. For example, individual tiddler fields are modules, too: there's a module that knows how to handle the tags field, and another that knows how to handle the special behaviour of the modified and created fields. Some plugin modules have further sub-plugins: the wikitext parser, for instance, accepts parsing rules as individual plugin modules.
In TiddlyWiki5, Plugins are bundles of tiddlers that are distributed and managed as one; Modules are JavaScript tiddlers with a module type identifying when and how they should be executed.
The tiddler $:/boot/boot.js is a barebones TiddlyWiki kernel that is just sufficient to load the core plugin modules and trigger a startup module to load up the rest of the application.
The boot kernel includes:
$tw.Tiddler class (and field definition plugins)$tw.Wiki class (and tiddler deserialization methods)Each module is an ordinary CommonJS module, using the require() function to access other modules and the exports global to return JavaScript values. The boot kernel smooths over the differences between Node.js and the browser, allowing the same plugin modules to execute in both environments.
In the browser, core/boot.js is packed into a template HTML file that contains the following elements in order:
<DIV> elementscore/bootprefix.js, containing a few lines to set up the plugin environment<SCRIPT> blockscore/boot.js, containing the boot kernelOn the server, core/boot.js is executed directly. It uses the Node.js local file API to load plugins directly from the file system in the core/modules directory. The code loading is performed synchronously for brevity (and because the system is in any case inherently blocked until plugins are loaded).
The boot process sets up the $tw global variable that is used to store all the state data of the system.
At the end of the boot process the StartupMechanism schedules the execution of startup modules to bring up the rest of TiddlyWiki.
The browse widget displays an HTML file browser button that allows the user to choose one or more files to import. It sends a WidgetMessage: tw-import-tiddlers carrying a JSON representation of the tiddlers imported from the files up through its parents. This message usually trapped by the NavigatorWidget which adds the tiddlers to the store and updates the story to display them.
The browse widget has no attributes, and ignores any contained content.
BT (née British Telecom) is the UK's largest telecommunications company. In 2007, Osmosoft was acquired by BT. JeremyRuston subsequently left BT in 2011.
Build the specified build targets for the current wiki. If no build targets are specified then all available targets will be built.
--build <target> [<target> ...]Build targets are defined in the tiddlywiki.info file of a wiki folder.
See TiddlyWikiFolders for details of defining build targets.
TiddlyWiki5 can be used to build older 2.x.x versions of TiddlyWikiClassic from their constituent components. Doing so involves these features:
tiddlywiki/classictools plugin, containing a deserializer module which allows tiddlers to be loaded from TiddlyWiki 2.x.x .recipe filesstripcomments format for the ViewWidget, which strips single line JavaScript comments starting //#stripTitlePrefix='yes' attribute of the FieldsWidget, which removes prefixes wrapped in curly braces from the title attribute{tiddler}HelloThere would be transformed to HelloThereTiddlyWikiClassic is built from the command line by running TiddlyWiki on Node.js. A typical usage would be:
node ../../tiddlywiki.js \
--verbose \
--load <path_to_recipe_file> \
--rendertiddler $:/core/templates/tiddlywiki2.template.html <path_to_write_index_file> text/plain \
|| exit 1The button widget displays an HTML <button> element that can perform a combination of optional actions when clicked:
The content of the <$button> widget is displayed within the button.
| Attribute | Description |
|---|---|
| to | The title of the tiddler to navigate to |
| message | The name of the widget message to send when the button is clicked |
| param | The optional parameter to the message |
| set | A TextReference to which a new value will be assigned |
| setTo | The new value to assign to the TextReference identified in the set attribute |
| popup | Title of a state tiddler for a popup that is toggled when the button is clicked |
| aria-label | Optional Accessibility label |
| title | Optional tooltip |
| class | An optional CSS class name to be assigned to the HTML element |
| style | An optional CSS style attribute to be assigned to the HTML element |
| selectedClass | An optional additional CSS class to be assigned if the popup is triggered or the tiddler specified in set already has the value specified in setTo |
| default | Default value if set tiddler is missing for testing against setTo to determine selectedClass |
The changecount macro returns a counter maintained by the TiddlyWiki core that tracks the number of modifications made to each tiddler. The changecount macro always applies to the tiddler named in the currentTiddler variable.
For example:
<<changecount>>Displays as:
0
Note how the changecount increases every time this tiddler is modified.
This release resolves a number of inconsistencies with the way that filters are handled. The changes mean that existing filters may need to be updated - particularly those that must deal with missing or shadow tiddlers.
Most filter operators act by choosing some or all of their source titles to pass through or re-order. Those that add new entries that are not drawn from the source list are referred to as selectors. Prior to 5.0.9-beta, a few filter operators were inconsistent in whether they filtered from the source list or selected new entries into it.
The specific changes are:
The sources for the all operator can be combined with the + character. For example, [all[shadows+tiddlers]] returns all shadow tiddlers and all ordinary tiddlers.
Previously, it was common to have [is[shadow]] at the start of a filter string to select all the shadow tiddlers. In 5.0.9 and above, this will not return all the shadow tiddlers, but instead just those ordinary tiddlers that are also shadow tiddlers (by virtue of having overridden one). The resolution is to use the new all operator. For example, consider this filter from 5.0.8:
[is[shadow]!has[draft.of]tag[$:/tags/AdvancedSearch]] [!is[shadow]!has[draft.of]tag[$:/tags/AdvancedSearch]] +[tag[$:/tags/AdvancedSearch]]In 5.0.9, that filter has been changed to:
[all[shadows+tiddlers]tag[$:/tags/AdvancedSearch]!has[draft.of]]Note how the all operator allows operations to be performed on tiddlers from combinations of sources.
[is[current]]One result of the changes is that [is[current]] now strictly filters from the source tiddlers; so, if the current tiddler is a missing tiddler not in the source list, then [is[current]] will return an empty list.
The solution is generally to use [all[current]] instead. It doesn't read as well, but has the required behaviour of returning just the current tiddler, regardless of whether it is in the source tiddlers.
There are minor changes to the way that the title and field operators work.
The title operator is a selector: it returns the specified title regardless of whether it is in the current source. title is used as the default operator if none is specified
The field operator is a filter: it only returns a subset of the source tiddlers. field is used as the default operator if the supplied operator is not defined (the supplied operator is passed as the suffix to the field operator, so [description[Missing]] is equivalent to [field:description[Missing]]).
The checkbox widget displays an HTML <input type="checkbox"> element that is dynamically bound to the presence or absence of a specified tag on a specified tiddler.
The content of the <$checkbox> widget is displayed within an HTML <label> element immediately after the checkbox itself. This means that clicking on the content will toggle the checkbox.
| Attribute | Description |
|---|---|
| tiddler | Title of the tiddler to manipulate (defaults to the WidgetVariable: currentTiddler) |
| tag | The name of the tag to which the checkbox should be bound |
You can use triple backticks ``` to mark code blocks:
``` This will be monospaced ```
The three backticks need to be at the start of the line and immediately followed by a newline, otherwise they won't be interpreted correctly.
Renders as:
This will be monospacedNote that some keyboard layouts treat the backtick as a dead key, making it hard to type. The trick is to type three backticks followed by a space. Alternatively, type all six backticks in one go, then a space, and then move the cursor back three characters to type or paste the content.
Colour palettes bind logical colour names (such as page-background) to actual CSS colours (such as #fe0).
Entire colour palettes are stored in a single data tiddler.
The title of the tiddler containing the current colour palette is identified by the tiddler $:/palette.
To retrieve a named colour from the current palette you can use the colour macro:
<<colour page-background>>The colour macro is defined like this:
\define colour(name)
<$transclude tiddler={{$:/palette}} index="$name$"/>
\endBy convention, each theme provides a default colour palette in the tiddler $:/config/DefaultPalette tiddler. Thus, setting the tiddler $:/theme to the string $:/config/DefaultPalette will revert to the palette packaged with the current theme (as long as it hasn't been redefined, since it is a shadow tiddler).
Palette tiddlers should have the following fields:
| Field | Description |
|---|---|
| title | Any title can be used, typically a system title starting with "$:/" |
| type | application/x-tiddler-dictionary to identify this tiddler as a data tiddler |
| tags | $:/tags/Palette to identify this tiddler as a palette |
| description | Description to be displayed in palette browser |
| text | Colour definitions (see below) |
The text of a palette tiddler consists of name value pairs like this:
foreground: #000
background: #fffWhen run under Node.js, TiddlyWiki supports a command line interface with these built-in commands.
TiddlyWiki is made much more useful by its vibrant community of users and OpenSource developers.
The TiddlyWiki discussion groups are mailing lists for talking about TiddlyWiki: requests for help, announcements of new releases and plugins, debating new features, or just sharing experiences.
Note that you do not need a Google Account to join the discussion groups. Subscribe by sending an email to mailto:tiddlywiki+subscribe@googlegroups.com or mailto:tiddlywikidev+subscribe@googlegroups.com.
New releases of TiddlyWiki, TiddlyDesktop and TiddlyFox are announced via the discussion groups and Twitter.
Local meetings of TiddlyWiki enthusiasts around the world:
If you are a TiddlyWiki enthusiast please consider starting a local TWIG in your area, it's a great way to spread the word about using TiddlyWiki
These are the concepts underlying TiddlyWiki. Understanding how these ideas fit together is the key to getting the most from TiddlyWiki.
Used in Internet protocols to indicate the type that should be used to interpret the content of a web resource.
Under TiddlyWiki5, the type field is gives the content type to apply to the main text field.
TiddlyWiki5 welcomes contributions to its code and documentation via GitHub. Please take a moment to read these notes to help make the process as smooth as possible.
Code contributions should follow the TiddlyWiki Coding Style Guidelines.
See ReportingBugs for information about how TiddlyWiki handles bug reports.
Like other OpenSource projects, TiddlyWiki5 needs a signed contributor license agreement from individual contributors. This is a legal agreement that allows contributors to assert that they own the copyright of their contribution, and that they agree to license it to the UnaMesa Association (the legal entity that owns TiddlyWiki on behalf of the community).
This is a first pass at a CLA for TiddlyWiki. Please let us know if we missed something important. If we do have to make essential changes to the CLA, there is a possibility that all contributors will need to sign it again
Create a GitHub pull request to add your name to cla-individual.md or cla-entity.md, with the date in the format (YYYY/MM/DD).
eg: Jeremy Ruston, @Jermolene, 2011/11/22
Thank you!
The CLA documents used for this project were created using Harmony Project Templates. "HA-CLA-I-LIST Version 1.0" for "CLA-individual" and "HA-CLA-E-LIST Version 1.0" for "CLA-entity"
TiddlyWiki5 welcomes contributions to its code and documentation via GitHub. Please take a moment to read these notes to help make the process as smooth as possible.
Code contributions should follow the TiddlyWiki Coding Style Guidelines.
See ReportingBugs for information about how TiddlyWiki handles bug reports.
Like other OpenSource projects, TiddlyWiki5 needs a signed contributor license agreement from individual contributors. This is a legal agreement that allows contributors to assert that they own the copyright of their contribution, and that they agree to license it to the UnaMesa Association (the legal entity that owns TiddlyWiki on behalf of the community).
This is a first pass at a CLA for TiddlyWiki. Please let us know if we missed something important. If we do have to make essential changes to the CLA, there is a possibility that all contributors will need to sign it again
Create a GitHub pull request to add your name to cla-individual.md or cla-entity.md, with the date in the format (YYYY/MM/DD).
eg: Jeremy Ruston, @Jermolene, 2011/11/22
Thank you!
The CLA documents used for this project were created using Harmony Project Templates. "HA-CLA-I-LIST Version 1.0" for "CLA-individual" and "HA-CLA-E-LIST Version 1.0" for "CLA-entity"
This file was automatically generated by TiddlyWiki5
The count widget displays the number of matches to a specified filter expression.
The content of the <$count> widget is ignored.
| Attribute | Description |
|---|---|
| filter | The filter expression to count |
This example shows how to create a sub-story within a tiddler that is independent of the main story.
Here's the code:
<$navigator story="MySubStoryList" history="MySubHistoryList">
Click this link to get started: HelloThere
<$list filter="[list[MySubStoryList]]" history="MySubHistoryList">
<div>
! <$button message="tw-close-tiddler" class="btn-invisible">{{$:/core/images/close-button}}</$button> <$view field="title"/>
<$transclude/>
</div>
</$list>
</$navigator>Note how you can open the HelloThere tiddler in the substory by clicking on the link below. Links within the substory open within the substory, and not in the main story.
Click this link to get started: HelloThere
The CurrentTiddler is the current tiddler during WikiText processing. A context tiddler is set by the TiddlerWidget. It allows you to write references like <$view field="title" format="link"/> in TemplateTiddlers without explicitly specifying the tiddler that it applies to.
You can create an n-dash with a double hyphen -- and an m-dash with a triple hyphen ---. For example – this is an example — and so is this
Data tiddlers provide a way to access blocks of JSON data within the text field of a tiddler.
The implementation of data tiddlers is preliminary, with some intentional limitations.
A native data tiddler must have:
type set to application/jsontext field For example, the history list tiddler is a data tiddler.
Other tiddler types with alternative formats can also be parsed to yield a block of data that behaves like a data tiddler.
The tiddler dictionary format is an alternative syntax for data tiddlers:
type is set to application/x-tiddler-dictionarytext field consists of one or more lines of the form <name>:<value>For example, the metrics of the Vanilla theme are a tiddler dictionary.
Currently, it is only possible to access the top level properties of the data using TextReference syntax.
For example, given a application/json tiddler containing:
{"a":"one","b":"two","c":"three"}Or the equivalent tiddler dictionary of type application/x-tiddler-dictionary:
a:one
b:two
c:threeWith either of those definitions {{TiddlerTitle##b}} would have the value two.
The ViewWidget accepts a template attribute that allows the format of date values to be specified. The format string is processed with the following substitutions:
| Token | Substituted Value |
|---|---|
DDD | Day of week in full (eg, "Monday") |
ddd | Short day of week (eg, "Mon") |
DD | Day of month |
0DD | Adds a leading zero |
DDth | Adds a suffix |
WW | ~ISO-8601 week number of year |
0WW | Adds a leading zero |
MMM | Month in full (eg, "July") |
mmm | Short month (eg, "Jul") |
MM | Month number |
0MM | Adds leading zero |
YYYY | Full year |
YY | Two digit year |
wYYYY | Full year with respect to week number |
wYY | Two digit year with respect to week number |
hh | Hours |
0hh | Adds a leading zero |
hh12 | Hours in 12 hour clock |
0hh12 | Hours in 12 hour clock with leading zero |
mm | Minutes |
0mm | Minutes with leading zero |
ss | Seconds |
0ss | Seconds with leading zero |
am or pm | Lower case AM/PM indicator |
AM or PM | Upper case AM/PM indicator |
TZD | Timezone offset |
\x | Used to escape a character that would otherwise have special meaning |
Note that other text is passed through unchanged, allowing commas, colons or other separators to be used.
| Template | Output |
|---|---|
DDth MMM YYYY | 16th February 2011 |
DDth MMM \M\M\M YYYY | 16th February MMM 2011 |
DDth mmm hh:mm:ss | 16th Feb 2011 11:38:42 |
These are definitions of technical words and phrases used in this documentation. (As distinct from the concepts that make up TiddlyWiki itself).
The most practical way to develop plugins is to use Node.js with the tiddlywiki5 repository to build your plugins, and to use GitHub to manage you files.
First read http://tiddlywiki.com/static/PluginMechanism.html.
Install Git from http://git-scm.com/downloads
Install Node.js from http://nodejs.org/
Hint: GitHub repositories cannot be grouped together into directories, so it is only possible to group by using a naming scheme, e.g. use 'TW5-' as a name prefix with tiddlywiki5 projects to group them together.
Go to https://github.com/ and create new a repository 'pluginname' - choose to add a readme file.
Choose a location in your file system (eg TW5) for you plugin project; issue commands to:
–create the directory–
mkdir TW5
–make a local read-only copy of the tiddlywiki5 repository–
git clone https://github.com/Jermolene/TiddlyWiki5.git TW5
–make a directory for your plugin–
cd TW5
cd plugins
mkdir yourname
cd yourname
mkdir pluginname
–make a local copy of you plugin repository–
git clone https://github.com/yourgithub/pluginname.git pluginname
–go to your files–
cd pluginname
Create the file plugin.info with content:
{
"title": "$:/plugins/yourgithub/pluginname",
"description": "summary of the plugin's purpose",
"author": "yourname",
"version": "0.0.1",
"core-version": ">=5.0.8",
"source": "https://github.com/yourgithub/pluginname",
"plugin-type": "plugin"
}For example files see the plugins in the tiddlywiki5 repository i.e. those located at plugins/tiddlywiki/ - Note in particular that files need to contain information that is used to tell tiddlywiki the name of the tiddler that is to be used in the tiddlywiki in place of the name of the file within the file system.
Modify editions/tw5.com/tiddlywiki.info to include a reference to your plugin directory, i.e. find "plugins": [ and add "yourname/pluginname".
From the TW5 directory issue command
./qbld.shthe resultant file (index.html) will be placed in the build directory, the default build directory is ../jermolene.github.com relative to TW5/
From plugins/yourname/pluginname/ issue commands to:
–add all files–
git add -A–commit to your local repository—
git commit -am "something meaningful about this check in"–copy local changes to github–
git pushThis is the main documentation hub for TiddlyWiki. See also TiddlyWiki for Developers.
These are the concepts underlying TiddlyWiki. Understanding how these ideas fit together is the key to getting the most from TiddlyWiki.
Widgets add dynamic functionality to WikiText.
When run under Node.js, TiddlyWiki supports a command line interface with these built-in commands.
Hints and tips to help you get the most from TiddlyWiki.
Download single file editions of version 5.0.13-beta of TiddlyWiki:
| Get started with an empty wiki | |
| Download a full copy of this site, including all the documentation |
For more advanced configurations, you can run TiddlyWiki on Node.js.
Tiddlers that have a draft.of field are treated as pending drafts of the tiddler specified in the field. Draft tiddlers should also have a draft.title field that specifies the title that will be given to the tiddler when it is saved.
Several features work in concert to give the desired behaviour for draft tiddlers:
tw-new-tiddler for creating a new tiddler in draft modetw-edit-tiddler for moving a tiddler into edit mode tw-cancel-tiddler for cancelling a tiddler out of edit modetw-save-tiddler for saving a draft tiddlerThe dropzone widget creates an area into which the user can drag files and other objects. It also supports pasting via the clipboard, although browser support is currently limited.
It sends a WidgetMessage: tw-import-tiddlers carrying a JSON representation of the tiddlers to be imported up through its parents. This message usually trapped by the NavigatorWidget which adds the tiddlers to the store and updates the story to display them.
The dropzone widget has no attributes, and displays any contained content within the dropzone.
The dropzone widget creates an HTML <div class="tw-dropzone"> to contain its content. During a drag operation the class tw-dragover is added. CSS is used to provide user feedback.
The following data transfer types are supported:
The edit bitmap widget provides a user interface in the browser for editing bitmap tiddlers. It is currently a primitive proof-of-concept, supporting resizing and painting with a single color and line width.
The content of the <$edit-bitmap> widget is ignored.
| Attribute | Description |
|---|---|
| tiddler | The tiddler to edit (defaults to the WidgetVariable: currentTiddler) |
The edit bitmap widget can be configured with these system tiddlers:
Michael Fogleman has written an Emacs major mode called tid-mode, which is for editing TiddlyWiki .tid files. It is derived from text-mode, uses the useful minor modes org-struct and subword, and updates the modified times when you save a .tid file.
He also wrote two helper functions for using TiddlyWiki in Emacs. The first opens a tiddlers directory in Dired; the second opens TiddlyWiki in the browser.
(defun open-wiki ()
"Opens a TiddlyWiki directory in Dired."
(interactive)
(dired "~/Dropbox/wiki/tiddlers/"))(defun browse-wiki ()
"Opens TiddlyWiki in the browser."
(interactive)
(browse-url "127.0.0.1:8080/"))This latter function may require specifying a browser:
(setq browse-url-browser-function 'browse-url-generic
browse-url-generic-program "chromium")You can bind either of these functions with the global-set-key function:
(global-set-key (kbd "C-c w") 'open-wiki)At the moment, these are not integrated into tid-mode.
The edit text widget provides a user interface in the browser for editing text tiddler fields. The editing element is dynamically bound to the underlying tiddler value: changes to the tiddler are instantly reflected, and any edits are instantly propogated.
By default, the edit text widget generates a <textarea> as the HTML editing element when the text field is edited, and a <input type="text"> element otherwise. This behaviour can be overridden with the tag and type attributes.
The content of the <$edit-text> widget is ignored.
| Attribute | Description |
|---|---|
| tiddler | The tiddler to edit (defaults to the WidgetVariable: currentTiddler) |
| field | The field to edit (defaults to text). Takes precedence over the index attribute |
| index | The index to edit |
| default | The default text to be provided when the target tiddler doesn't exist |
| class | A CSS class to be assigned to the generated HTML editing element |
| placeholder | Placeholder text to be displayed when the edit field is empty |
| focusPopup | Title of a state tiddler for a popup that is displayed when the editing element has focus |
| tag | Overrides the generated HTML editing element tag |
| size | The size of the input field (in characters) |
| type | Overrides the generated HTML editing element type attribute |
The edit widget provides a general purpose interface for editing a tiddler. It dynamically chooses the appropriate widget depending on the type of the tiddler (currently either the EditTextWidget or the EditBitmapWidget).
The content of the <$edit> widget is ignored.
| Attribute | Description |
|---|---|
| tiddler | The tiddler to edit (defaults to the WidgetVariable: currentTiddler) |
| field | The field to edit (defaults to text). Takes precedence over the index attribute |
| index | The index to edit |
| class | A CSS class to be added the generated editing widget |
TiddlyWiki5 allows the entire content of a TiddlyWiki HTML file to be encrypted with the Stanford JavaScript Crypto Library. Opening an encrypted TiddlyWiki in the browser prompts for a password before decrypting and displaying the content.
For instructions on how to use TiddlyWiki5's encryption features, see Saving with Encryption.
The EncryptionMechanism is implemented with the following elements:
The encrypt widget renders a filtered list of tiddlers to an encrypted block with the password currently held in the PasswordVault. The encrypted block can subsequently be decrypted by the TiddlyWiki5 BootMechanism. See the EncryptionMechanism for more details.
The content of the <$encrypt> widget is ignored.
| Attribute | Description |
|---|---|
| filter | Filter defining the tiddlers to be included in the encrypted block. If not specified then all non-system tiddlers are used |
TiddlyWiki on Node.js supports the following OS environment variables for specifying a colon-delimited list of paths to search for plugins and editions:
TIDDLYWIKI_PLUGIN_PATH - Search path for ordinary pluginsTIDDLYWIKI_THEME_PATH - Search path for themesTIDDLYWIKI_LANGUAGE_PATH - Search path for languagesTIDDLYWIKI_EDITION_PATH - Search path for editions (used by the InitCommand)The additional paths should each point to folders structured like the equivalent directories in the TiddlyWiki5 GitHub repository: the plugin, theme and language directories contain publisher/pluginname/<files> while the edition directories contain editionname/<files>
For example:
TIDDLYWIKI_PLUGIN_PATH=~/MyPluginStore
tiddlywiki mywiki --build indexThis collection showcases inspiring and interesting examples of TiddlyWiki being used in the wild.
Submit new entries to this collection via GitHub, Twitter or by posting in the TiddlyWiki Groups.
A study notebook for the Bible.
A manifesto for the preservation of free speech through the exchange of randomized data.
Worried that using encryption will make you stand out from the crowd?
Do something about it!
Preserve our rights to free speech and association by sending Randomized Data to your friends and friends of friends – only to those who have given their consent – and encourage them to do the same.
We call data like that Freedom Bits.
A thesis notebook based on TiddlyWiki.
This is an example of a thesis notebook powered by TiddlyWiki 5.0.8-beta.
TiddlyWiki is a great piece of software created by Jeremy Ruston. It allows you, among other things, to take notes, organize ideas, store information, and display all your stuff the way you want. It is an incredibly flexible tool you can adapt to fit almost all your needs.
This TiddlyWiki has been customized to serve as a philosophy notebook centered around authors, books and papers, concepts and theories, and personal notes. I use it along with Zotero, which is a dedicated bibliography software. Both are free, open source projects. TiddlyWiki can be downloaded at http://tiddlywiki.com.
External images in TiddlyWiki are tiddlers that point to the URI of an image, rather than embedding the full image data. They can perform better than embedded images, particularly with large numbers or sizes of images. However, using them breaks the single file pattern of TiddlyWiki.
External images are used in the browser. They can be created by the Node.js configuration when it builds a TiddlyWiki, or they can be created manually within the browser.
An external image is an ordinary image tiddler that has a _canonical_uri field containing the URI of the image. The URI can be absoluate or relative to the HTML document. If the canonical URI is provided then the text field of the tiddler is ignored and so should be omitted.
To manually create an external image just create the tiddler with the appropriate image content type, and add a _canonical_uri field with a URI pointing to the actual image location.
The following steps are used to create a static HTML file version of a wiki accompanied by an images folder containing the referenced external images:
Note the image files must be saved before they are externalised. Externalising them destroys the text field within the in-memory copy of the wiki store, meaning that attempts to save them will fail.
For an example see the externalimages build target of the demo tw5.com wiki:
--savetiddlers [is[image]] images
--setfield [is[image]] _canonical_uri $:/core/templates/canonical-uri-external-image text/plain
--setfield [is[image]] text "" text/plain
--rendertiddler $:/core/save/all externalimages.html text/plainThe following --savetiddlers command can be used to save the images of a wiki into an images subfolder:
--savetiddlers [is[image]] imagesTwo --setfield commands are used: the first sets the _canonical_uri field to a URI derived from the title of the tiddler, and the second clears the text field.
--setfield [is[image]] _canonical_uri $:/core/templates/canonical-uri-external-image text/plain
--setfield [is[image]] text "" text/plainThe template tiddler $:/core/templates/canonical-uri-external-image contains:
<!-- This template is used to assign the ''_canonical_uri'' field to external images. Change the `./images/` part to a different base URI. The URI can be relative or absolute. --> ./images/<$view field="title" format="doubleurlencoded"/>
Note that these operations modify the tiddlers in the wiki store and so may affect the operation of subsequent commands.
You can't edit an external image directly in the browser except by changing the URI field to point to a different image.
The deep internal changes mean that TiddlyWiki version 5 is not compatible with previous versions, using different plugins, themes and so on. Content prepared for previous versions of TiddlyWiki will need massaging to work properly. When asking or searching for help be sure to specify TiddlyWiki5 (or TW5).
Federatial Limited is a software consultancy founded by JeremyRuston specializing in understanding the impact of the web on the way that we work together.
See http://federatial.com/ and http://twitter.com/federatial for more information.
The field mangler widget manipulates the fields and tags of a tiddler. It does so in response to the following WidgetMessages:
| Message | Description |
|---|---|
| tw-remove-field | Remove the field specified in event.param |
| tw-add-field | Add the field specified in event.param |
| tw-remove-tag | Remove the tag specified in event.param |
| tw-add-tag | Add the tag specified in event.param |
The field mangler widget displays any contained content, and responds to WidgetMessages dispatched within it.
| Attribute | Description |
|---|---|
| tiddler | Title of the tiddler to manipulate (defaults to the WidgetVariable: currentTiddler) |
The fields widget renders each field of a specified tiddler through a simple text template. A list of fields to exclude can be provided. It is used internally by TiddlyWiki5, notably by the FileSavingMechanism.
The provided template is rendered with the following special substitutions:
| Symbol | Substitution |
|---|---|
| $name$ | Field name |
| $value$ | Field value |
| $encoded_value$ | HTML encoded form of field value |
The content of the <$fields> widget is ignored.
| Attribute | Description |
|---|---|
| tiddler | Title of the tiddler from which the fields are to be displayed (defaults to the WidgetVariable: currentTiddler) |
| template | Text of the template (see above) |
| exclude | Lists of fields to be excluded (defaults to "text") |
| stripTitlePrefix | If set to "yes" then curly bracketed prefixes are removed from titles (for example {prefix}HelloThere converts to HelloThere) |
The stripTitlePrefix attribute is used when building TiddlyWiki Classic; see editions/tw2 in the TiddlyWiki5 repo.
The after filter operator returns the tiddler from the current list that is after the tiddler named in the operand.
The following examples assume a tiddler called MyList with a list field containing:
one two three four five| Filter String | Description |
|---|---|
[list[MyList]after[two]] | Returns three |
[list[MyList]after[five]] | Returns an empty list |
[list[MyList]after{!!title}] | Returns five if the current tiddler is four |
See also FilterOperator: before, FilterOperator: previous and FilterOperator: next.
The all filter operator is used to select combinations of lists of tiddlers for subsequent operations.
The operand of the all operator is a list of names of tiddler sources joined with +.
For example:
| Filter String | Description |
|---|---|
[all[tiddlers]] | Selects all 'real' tiddlers (both system and non-system), excluding shadow tiddlers |
[all[shadows]] | Selects all ShadowTiddlers, including those that have been overridden with real tiddlers |
[all[shadows+tiddlers]] | Selects all ShadowTiddlers and all 'real' tiddlers together |
[all[current]] | Selects the current tiddler |
[all[missing]] | Selects all MissingTiddlers |
[all[orphans]] | Selects all OrphanTiddlers |
The backlinks filter operator replaces the current list with a list of the non-system tiddlers that link to them.
For example:
| Filter String | Description |
|---|---|
[[HelloThere]backlinks[]] | Selects all tiddlers that contain links to the tiddler HelloThere |
[tag[Personal]backlinks[]] | Selects all tiddlers that contain links to tiddlers tagged Personal |
[all[current]backlinks[]] | Selects all tiddlers that contain links to the current tiddler |
The before filter operator returns the tiddler from the current list that is before the tiddler named in the operand.
The following examples assume a tiddler called MyList with a list field containing:
one two three four five| Filter String | Description |
|---|---|
[list[MyList]before[two]] | Returns one |
[list[MyList]before[one]] | Returns an empty list |
[list[MyList]before{!!title}] | Returns three if the current tiddler is four |
See also FilterOperator: after, FilterOperator: previous and FilterOperator: next.
The butfirst filter operator is a synonym for FilterOperator: rest.
Without an operand, the butlast filter operator returns all but the last entry in the current list. The optional operand specifies the number of entries to omit.
For example:
| Filter String | Description |
|---|---|
one two three four five +[butlast[]] | Returns one, two, three, four |
one two three four five +[butlast[2]] | Returns one, two, three |
The commands filter operator replaces the current list with a list of the available commands (see the HelpCommand for details).
For example:
| Filter String | Description |
|---|---|
[commands[]] | Returns a list of the available command names |
The each filter operator filters the current list to leave only the first tiddler with each distinct value for a specified field.
For example:
| Filter String | Description |
|---|---|
[all[tiddlers]sort[title]each[type]] | Returns a list of the first tiddler with each distinct type field |
The each operator can be used to group tiddlers. For example, the following example creates a list of tiddlers split into types:
The eachday filter operator filters the current list to leave only the first tiddler that has a distinct value for a specified date field.
For example:
| Filter String | Description |
|---|---|
[eachday[created]] | Returns a list of the first tiddler created on each distinct day |
The eachday operator can be used to group tiddlers. For example, the following wiki text creates a list of the number of tiddlers that were modified on each day:
24 June 2014: 3 modifications
21 June 2014: 2 modifications
19 June 2014: 4 modifications
17 June 2014: 5 modifications
14 June 2014: 3 modifications
13 June 2014: 2 modifications
12 June 2014: 1 modifications
11 June 2014: 1 modifications
10 June 2014: 1 modifications
9 June 2014: 2 modifications
7 June 2014: 1 modifications
4 June 2014: 2 modifications
30 May 2014: 1 modifications
26 May 2014: 2 modifications
17 May 2014: 1 modifications
16 May 2014: 3 modifications
13 May 2014: 1 modifications
12 May 2014: 2 modifications
9 May 2014: 1 modifications
5 May 2014: 2 modifications
2 May 2014: 3 modifications
27 April 2014: 2 modifications
26 April 2014: 1 modifications
25 April 2014: 2 modifications
24 April 2014: 1 modifications
19 April 2014: 3 modifications
18 April 2014: 2 modifications
16 April 2014: 2 modifications
15 April 2014: 1 modifications
10 April 2014: 43 modifications
9 April 2014: 1 modifications
3 April 2014: 2 modifications
27 March 2014: 1 modifications
24 March 2014: 2 modifications
22 March 2014: 1 modifications
21 March 2014: 10 modifications
20 March 2014: 4 modifications
18 March 2014: 1 modifications
17 March 2014: 2 modifications
12 March 2014: 5 modifications
3 March 2014: 1 modifications
2 March 2014: 3 modifications
28 February 2014: 3 modifications
26 February 2014: 17 modifications
25 February 2014: 11 modifications
24 February 2014: 2 modifications
23 February 2014: 1 modifications
22 February 2014: 3 modifications
21 February 2014: 1 modifications
20 February 2014: 1 modifications
17 February 2014: 2 modifications
16 February 2014: 1 modifications
14 February 2014: 2 modifications
13 February 2014: 1 modifications
11 February 2014: 8 modifications
10 February 2014: 1 modifications
6 February 2014: 6 modifications
29 January 2014: 2 modifications
28 January 2014: 1 modifications
26 January 2014: 3 modifications
25 January 2014: 3 modifications
22 January 2014: 2 modifications
20 January 2014: 1 modifications
19 January 2014: 3 modifications
13 January 2014: 1 modifications
12 January 2014: 1 modifications
11 January 2014: 1 modifications
7 January 2014: 2 modifications
5 January 2014: 2 modifications
4 January 2014: 4 modifications
3 January 2014: 3 modifications
2 January 2014: 1 modifications
1 January 2014: 3 modifications
30 December 2013: 1 modifications
29 December 2013: 1 modifications
28 December 2013: 7 modifications
24 December 2013: 2 modifications
22 December 2013: 1 modifications
21 December 2013: 1 modifications
18 December 2013: 1 modifications
15 December 2013: 2 modifications
14 December 2013: 4 modifications
13 December 2013: 1 modifications
12 December 2013: 6 modifications
11 December 2013: 3 modifications
7 December 2013: 1 modifications
6 December 2013: 3 modifications
5 December 2013: 5 modifications
3 December 2013: 3 modifications
30 November 2013: 2 modifications
29 November 2013: 7 modifications
28 November 2013: 2 modifications
22 November 2013: 1 modifications
15 November 2013: 2 modifications
12 November 2013: 1 modifications
11 November 2013: 1 modifications
10 November 2013: 1 modifications
9 November 2013: 1 modifications
8 November 2013: 2 modifications
1 November 2013: 7 modifications
30 October 2013: 11 modifications
7 September 2013: 2 modifications
1 September 2013: 1 modifications
30 August 2013: 2 modifications
29 August 2013: 1 modifications
28 August 2013: 3 modifications
26 August 2013: 1 modifications
25 August 2013: 19 modifications
23 August 2013: 1 modifications
22 August 2013: 1 modifications
20 August 2013: 1 modifications
9 August 2013: 2 modifications
5 July 2013: 1 modifications
13 June 2013: 2 modifications
8 May 2013: 1 modifications
6 May 2013: 1 modifications
2 March 2013: 1 modifications
The field filter operator filters the current list according to whether a field matches a specified value.
The operand is the value to match, and the suffix is used to identify the field. For example:
| Filter String | Description |
|---|---|
[field:modifier[JeremyRuston]] | Returns a list of the tiddlers created by JeremyRuston |
[modifier[JeremyRuston]] | Returns a list of the tiddlers created by JeremyRuston |
Note that if an unknown filter operator [unknown[xxx]] is encountered it is interpreted as [field:unknown[xxx]].
|
Note that if an unknown filter operator `[unknown[xxx]]` is encountered it is interpreted as `[field:unknown[xxx]]`.
The first filter operator returns the first entries in the current list. The optional operand specifies the number of entries to return.
For example:
| Filter String | Description |
|---|---|
one two three +[first[]] | Returns one |
one two three +[first[2]] | Returns one, two |
The get filter operator replaces the titles of the tiddlers in the current list with the values of the field specified by the operand.
For example:
| Filter String | Description |
|---|---|
[all[current]get[draft.of]] | If the current tiddler is a draft, returns the original tiddler, otherwise returns an empty list |
The has filter operator chooses tiddlers from the current list that have a non-empty value for the field specified in the operand.
For example:
| Filter String | Description |
|---|---|
[has[modifier]] | Returns tiddlers that have a modifier field |
The indexes filter operator returns a list of all the property indexes found in the DataTiddlers in the current list. Tiddlers that are not DataTiddlers are ignored.
For example:
| Filter String | Description |
|---|---|
[[MyData]indexes[]] | Returns the indexes of all properties in the data tiddler MyData |
[{$:/palette}indexes[]sort[title]] | Returns the names of all the colours defined in the current colour palette |
The is filter operator selects tiddlers from the current list according to their membership of the category specified in the operand:
[is[current]] - returns any tiddler that matches the title of the current tiddler[is[image]] - tiddlers that contain an image (eg, GIF, JPEG, PNG etc.)[is[missing]] - MissingTiddlers that are referenced but undefined[is[orphan]] - OrphanTiddlers that are not referenced from any other tiddler[is[shadow]] - tiddlers that are ShadowTiddlers[is[system]] - tiddlers that are SystemTiddlers[is[tiddler]] - tiddlers that are not MissingTiddlers[is[tag]] - tiddlers that are being used as tagsFor example:
| Filter String | Description |
|---|---|
[tag[task]is[shadow]] | Returns ShadowTiddlers tagged task |
[tag[task]!is[system]] | Returns non-SystemTiddlers tagged task |
[is[shadow]] | Returns ShadowTiddlers that have been overridden by a 'real' tiddler |
[!is[shadow]] | Returns ordinary tiddlers that are not shadow tiddlers |
[!is[tag]] | Returns all tiddlers that are not being used as tags |
[is[missing]] | Returns an empty list (see note below) |
Note that the is filter operator strictly filters the current list by choosing whether or not to include each one in the output. It never adds tiddlers to the results that are not already listed. This means that when used at the start of a run of filter operators the is operator will be choosing from the currently existing tiddlers, and so will never return missing tiddlers, or shadow tiddlers that haven't been overridden.
The last filter operator returns the last entries in the current list. The optional operand specifies the number of entries to return.
For example:
| Filter String | Description |
|---|---|
one two three +[last[]] | Returns three |
one two three +[last[2]] | Returns two, three |
The limit filter operator trims the current list to the length specified in the operator. Usually the first tiddlers in the list are returned; preceding the operator with ! causes it to instead return the last tiddlers in the list.
For example:
| Filter String | Description |
|---|---|
[sort[modified]!limit[20]] | Returns the titles of the last 20 tiddlers to have been modified |
[has[created]sort[created]limit[10]] | Returns the titles of the oldest 10 tiddlers to have been created |
The links filter operator replaces the current list with a list of the targets of outgoing links from those tiddlers.
For example:
| Filter String | Description |
|---|---|
[[HelloThere]links[]] | Returns the titles of tiddlers linked from HelloThere |
[all[current]links[]] | Returns the titles of tiddlers linked from the current tiddler |
The list filter operator replaces the current list with the list contained in the TextReference specified in the operand. The default field for the text reference is list.
Preceding the operator name with ! inverts the logic so that the filter only returns the tiddlers in the current list that are not listed in the specified list.
For example:
| Filter String | Description |
|---|---|
[list[HelloThere]] | Returns the list of tiddlers in the list field of the tiddler HelloThere |
[list[HelloThere!!mylist]] | Returns the list of tiddlers in the mylist field of the tiddler HelloThere |
The listed filter operator returns the titles of the tiddlers that have list fields that contain any members of the current list. The optional operand can be used to specify a different field.
For example:
| Filter String | Description |
|---|---|
[[HelloThere]listed[]] | Returns the titles of any tiddlers containing HelloThere in their list fields |
[all[current]listed[my-special-list]] | Returns the titles of any tiddlers containing the current tiddler in their my-special-list fields |
The modules filter operator treats the current list as a list of module types, and returns the titles of all of the modules of those types.
For example:
| Filter String | Description |
|---|---|
[[filteroperator]modules[]] | Returns a list of the modules of type filteroperator |
See also FilterOperator: moduletypes.
The moduletypes filter operator replaces the current list with a list of the types of the currently loaded modules.
For example:
| Filter String | Description |
|---|---|
[moduletypes[]] | Returns a list of the types of the currently loaded modules |
See also FilterOperator: modules.
The next filter operator takes each tiddler in the current list and looks it up in the list field of the tiddler specified in the operand, and then returns the immediately following tiddler title.
The following examples assume a tiddler called MyList with a list field containing:
one two three four five| Filter String | Description |
|---|---|
[[three]next[MyList]] | Returns four |
[[five]next[MyList]] | Returns an empty list |
one three +[next[MyList]] | Returns two, four |
See also FilterOperator: previous.
The nsort filter operator sorts the current list as numeric values. String values are sorted case insensitively (upper and lower case letters are considered equivalent). Preceding the operator with ! reverses the sort order.
For example:
| Filter String | Description |
|---|---|
10 010 1000 100 +[nsort[]] | Returns 10, 010, 100, 1000 |
10 010 alpha 1000 100 +[nsort[]] | Returns 10, 010, 100, 1000, alpha |
See also FilterOperator: sort, FilterOperator: sortcs and FilterOperator: nsortcs.
The nsortcs filter operator sorts the current list as numeric values. String values are sorted case sensitively (upper and lower case letters are considered different). Preceding the operator with ! reverses the sort order.
For example:
| Filter String | Description |
|---|---|
10 010 1000 100 +[nsortcs[]] | Returns 10, 010, 100, 1000 |
10 010 alpha 1000 100 +[nsortcs[]] | Returns 10, 010, 100, 1000, alpha |
See also FilterOperator: sort, FilterOperator: sortcs and FilterOperator: nsort.
Without an operand, the nth filter operator returns the first entry in the current list. The optional operand specifies the number of entries to return.
For example:
| Filter String | Description |
|---|---|
one two three four five +[nth[]] | Returns one |
one two three four five +[nth[3]] | Returns three |
The plugintiddlers filter operator returns the titles of the shadow tiddlers within any plugin tiddlers in the current list.
For example:
| Filter String | Description |
|---|---|
[[$:/core]plugintiddlers[]] | Returns a list of the shadow tiddlers within the $:/core module |
See also FilterOperator: shadowsource.
The prefix filter operator returns the titles in the current list that start with a specified prefix. If the prefix operator is preceded by ! then it returns the titles that do not start with the specified prefix.
For example:
| Filter String | Description |
|---|---|
[tag[task]!prefix[hidden]] | Returns tiddlers tagged task whose titles do not start with hidden |
[prefix[$:/]] | Equivalent to [is[system]] |
See also FilterOperator: removeprefix.
The previous filter operator takes each tiddler in the current list and looks it up in the list field of the tiddler specified in the operand, and then returns the immediately preceding tiddler title.
The following examples assume a tiddler called MyList with a list field containing:
one two three four five| Filter String | Description |
|---|---|
[[three]previous[MyList]] | Returns two |
[[one]previous[MyList]] | Returns an empty list |
two four +[previous[MyList]] | Returns one, three |
See also FilterOperator: next.
The removeprefix filter operator returns the titles in the current list that start with a specified prefix with the prefix removed.
For example:
| Filter String | Description |
|---|---|
tid-one tid-two three +[removeprefix[tid-]] | Returns one, two |
See also FilterOperator: prefix.
Without an operand, the rest filter operator returns all but the first entry in the current list. The optional operand specifies the number of entries to omit.
For example:
| Filter String | Description |
|---|---|
one two three four five +[rest[]] | Returns two, three, four, five |
one two three four five +[rest[2]] | Returns three, four, five |
The reverse filter operator reverses the order of the titles in the current list.
For example:
| Filter String | Description |
|---|---|
one two three +[reverse[]] | Returns the list three, two, one |
The sameday filter operator filters the current list to leave only those tiddlers whose modified field is on the same day as the date provided as the operand. The optional suffix allows a different field to be specified.
For example:
| Filter String | Description |
|---|---|
[sameday[20140410]] | Returns a list of the tiddlers modified on the 10th April 2014 |
[sameday:created[20140410]] | Returns a list of the tiddlers created on the 10th April 2014 |
See FilterOperator: eachday for an example.
The search filter operator filters the current list to leave only those tiddlers that include the operand text in their title, body or tags. Preceding the operator with ! returns all tiddlers that do not include the specified text. The search is case-insenstive.
For example:
| Filter String | Description |
|---|---|
[search[alsatian]] | Returns a list of the tiddlers containing the text "alsatian" |
[all[shadows]search[alsatian]] | Returns a list of the shadow tiddlers containing the text "alsatian" |
The shadowsource filter operator returns the titles of the plugin tiddlers containing any ShadowTiddlers in the current list.
For example:
| Filter String | Description |
|---|---|
[[$:/core/copyright.txt]shadowsource[]] | Returns $:/core, which is the plugin that contains the shadow tiddler $:/core/copyright.txt |
See also FilterOperator: plugintiddlers.
The sort filter operator sorts the current list case insensitively (upper and lower case letters are considered equivalent). Preceding the operator with ! reverses the sort order.
For example:
| Filter String | Description |
|---|---|
one two three four +[sort[]] | Returns four, one, three, two |
one two Three four +[sort[]] | Returns four, one, Three, two |
See also FilterOperator: nsort, FilterOperator: sortcs and FilterOperator: nsortcs.
The sortcs filter operator sorts the current list case sensitively (upper and lower case letters are considered different). Preceding the operator with ! reverses the sort order.
For example:
| Filter String | Description |
|---|---|
one two Three four +[sortcs[]] | Returns Three, four, one, two |
See also FilterOperator: sort, FilterOperator: nsort and FilterOperator: nsortcs.
The tag filter operator returns the tiddlers in the current list that have the tag specified in the operand. Preceding the operator with ! returns tiddlers that do not have the specified tag.
For example:
| Filter String | Description |
|---|---|
[tag[mytag]] | Returns all tiddlers tagged mytag |
[all[shadows]tag[mytag]] | Returns all ShadowTiddlers tagged mytag |
[all[shadows+tiddlers]tag[mytag]] | Returns all ShadowTiddlers and non-ShadowTiddlers tagged mytag |
[!tag[mytag]] | Returns all tiddlers not tagged mytag |
[tag[mytag]!tag[exclude]] | Returns all tiddlers tagged mytag that are not tagged mytag |
See also FilterOperator: tagging, FilterOperator: tags and FilterOperator: untagged.
The tagging filter operator returns all the tiddlers that are tagged by the tiddlers in the current list.
For example:
| Filter String | Description |
|---|---|
[[mytag]tagging[]] | Returns all tiddlers tagged mytag |
[all[current]tagging[]] | Returns all tiddlers tagged by the current tiddler |
See also FilterOperator: tag, FilterOperator: tags and FilterOperator: untagged.
The tags filter operator returns all the tags present on the tiddlers in the current list.
For example:
| Filter String | Description |
|---|---|
[[mytiddler]tags[]] | Returns all tags for the tiddler mytiddler |
[all[shadows+tiddlers]tags[]] | Returns all the tags used on ShadowTiddlers or non-ShadowTiddlers |
See also FilterOperator: tag, FilterOperator: tagging and FilterOperator: untagged.
The title filter operator replaces the current list with the title specified in the operand.
For example:
| Filter String | Description |
|---|---|
[[mytiddler]] | Returns the title mytiddler |
[title[mytiddler]] | Returns the title mytiddler |
Note that the title operator is the default when no operator name is specified.
The untagged filter operator selects from the current list any tiddlers that do not have any tags.
For example:
| Filter String | Description |
|---|---|
[untagged[]] | Returns the titles of all tiddlers without tags |
[all[shadows]untagged[]] | Returns all the ShadowTiddlers without tags |
See also FilterOperator: tag, FilterOperator: tagging and FilterOperator: tags.
The full list of available filter operators is:
Available character formatting includes:
`backticks` for code``double backticks allows `embedded` backticks``''bold'' for bold text//italic// for italic text__underscore__ for underscored text^^superscript^^ for superscript text,,subscript,, for subscripted text~~strikethrough~~ for See also: Code Blocks in WikiText
A manifesto for the preservation of free speech through the exchange of randomized data.
Worried that using encryption will make you stand out from the crowd?
Do something about it!
Preserve our rights to free speech and association by sending Randomized Data to your friends and friends of friends – only to those who have given their consent – and encourage them to do the same.
We call data like that Freedom Bits.
TiddlyWiki is designed with the long term needs of its users in mind. Because it is OpenSource and needs no infrastructure, we can be confident that all we'll need to access a TiddlyWiki file even in the far future is an ordinary HTML browser. If you're starting to use TiddlyWiki at the beginning of your career you can be confident that it will carry you through to retirement.
TiddlyWiki5 can be used to generate static HTML representations of a TiddlyWiki that doesn't need JavaScript.
There is much flexibility in how the static HTML is generated. The following scenarios are all illustrated on http://tiddlywiki.com.
You can explore a static representation of this TiddlyWiki at static.html. That file is a static snapshot of the current DefaultTiddlers. Any tiddlers that it links to are referred to via URLs of the form /static/HelloThere.html that point to static snapshots of individual tiddlers. The tiddler HTML files reference a static.css stylesheet file.
The included bld.sh script includes these commands that are involved in generating the sample static version of the TiddlyWiki5 site:
--rendertiddler $:/core/templates/static.template.html $TW5_BUILD_OUTPUT/static.html text/plain \
--rendertiddler $:/core/templates/static.template.css $TW5_BUILD_OUTPUT/static/static.css text/plain \
--rendertiddlers [!is[system]] $:/core/templates/static.tiddler.html $TW5_BUILD_OUTPUT/static text/plain \The first RenderTiddlerCommand saves the static version of the DefaultTiddlers, the second saves the stylesheet, and the final RenderTiddlersCommand generates the HTML representations of individual tiddlers.
It is also possible to produce a single HTML file that contains static representations of tiddlers, and uses standard HTML anchor links to jump between them.
For example: alltiddlers.html
The example is built by the following line in bld.sh:
--rendertiddler $:/core/templates/alltiddlers.template.html $TW5_BUILD_OUTPUT/alltiddlers.html text/plain \This brief tutorial takes you through the basics of saving changes with a standalone TiddlyWiki5 file.
TiddlyWiki is very flexible, and there are many different ways to use it. Here we're focusing on using it as a standalone file in the browser, which is a good choice for most users as it doesn't require any special knowledge or tools. For more options you can also run TiddlyWiki on Node.js.
Video Tutorials are available, too.
This method of saving changes is clunky but has the advantage of working on almost all desktop browsers, and many mobile browsers.
If the button doesn't work save this link: http://tiddlywiki.com/empty.html
Your browser may ask you to accept the download before it begins
.html or .htm extensionTip: most browsers have an option to prompt each time for the download location. This allows you to select the existing version of the file and replace it.
Saving changes as described above is quite inconvenient because of the degree of manual intervention that browsers require. The following alternative method is recommended for everyone who is able to use Mozilla's Firefox browser.
If you're using Firefox for Android, see the instructions for Saving with TiddlyFox on Android.
.html or .htm extensionSaving with Encryption explains how to use TiddlyWiki's built-in encryption to protect your content with a password.
You can also try:
Some suggestions for streamlining working with GoogleChrome.
By default, GoogleChrome displays a confirmation prompt at the bottom of the browser window before downloading the TiddlyWiki file. Once confirmed, the file is downloaded to the default Downloads folder under a filename determined by the browser.
In Chrome settings, the advanced option "Ask where to save each file before downloading" changes this behaviour so that when you click the save button the browser displays a file picker dialogue that lets the user choose the name and location of the file, thus making it more straightforward to replace the current version of the file with the new one.
This is cell B2, which is also transcluding A2: The A2 is a road from London through Kent.
The video widget is not yet (re)implemented.
The grid widget assembles tiddlers into a tabular grid based on their titles. For example:
<$grid prefix="GridDemo" rows=3 cols=3/>
In this case, the following tiddlers will be rendered:
|GridDemo_A_1 |GridDemo_A_2 |GridDemo_A_3 |
|GridDemo_B_1 |GridDemo_B_2 |GridDemo_B_3 |
|GridDemo_C_1 |GridDemo_C_2 |GridDemo_C_3 |
The result is:
<$grid prefix="GridDemo" rows=3 cols=3/>The usual handling of paragraphs in wikitext causes single line breaks to be ignored, and double linebreaks to be interpreted as the end of a paragraph.
This behaviour isn't convenient when dealing with material that incorporates hard linebreaks - for instance, poetry. You can mark a block of content as containing hard line breaks like this:
Headings are specified with one or more leading ! characters:
! This is a level 1 heading
!! This is a level 2 heading
!!! This is a level 3 headingCSS classes can be assigned to individual headings like this:
!.myStyle This heading has the class `myStyle`Welcome to TiddlyWiki, a complete interactive wiki in JavaScript. It can be used as a single HTML file in the browser or as a powerful Node.js application. It is highly customisable: the entire user interface is itself implemented in hackable WikiText.
This is version 5.0.13-beta of TiddlyWiki, a major reboot designed for the next 25 years. It is currently in beta (see the detailed ReleaseHistory). There is a RoadMap for moving to the full release. It is a great time to get involved and support the future development of TiddlyWiki.
TiddlyWiki is a free, open source project that depends on your love and support for its survival.
Displays help text for a command:
--help [<command>]If the command name is omitted then a list of available commands is displayed.
If you find TiddlyWiki useful, there are lots of ways you can help assure its future and make it better.
OpenSource projects like TiddlyWiki thrive on the feedback and engagement of users. TiddlyWiki becomes more useful to everyone as more and more people use it. So, if you find TiddlyWiki useful, spread the word. The best possible way to assure its future is for it to become a hundred times more popular than before.
There are many ways you can contribute to TiddlyWiki:
The main TiddlyWiki documentation and code lives on GitHub, and welcomes contributions:
The system tiddler $:/HistoryList keeps track of a list of tiddlers comprising the navigation history. Each time you click on a link to a tiddler, the title of the target tiddler is added to the top of the stack.
The history list is stored in JSON to allow additional details about the coordinates of the DOM node that initiated the navigation.
The history list also maintains the field current-tiddler that contains the name of the tiddler at the top of the stack. This field can be used like so:
<$list filter="[list[$:/StoryList]]" history="$:/HistoryList" storyview="pop">
<$button message="tw-close-tiddler" class="btn-invisible btn-mini">×</$button> <$link to={{!!title}}><$view field="title"/> <$reveal type="match" state="$:/HistoryList!!current-tiddler" text=<<currentTiddler>>>✓</$reveal></$link>
</$list>Which renders the same as the "Open" sidebar tab, with the addition of a tick against the tiddler that was last navigated to.
You can include a horizontal rule with three or more dashes on their own on a line:
First install TiddlyWiki as described in Installing TiddlyWiki on Node.js.
~/MyWiki)tiddlywiki.info containing the following text:{"themes": ["tiddlywiki/vanilla","tiddlywiki/snowwhite"]}tiddlerseditions/empty folder from the TiddlyWiki5 repo~/MyWiki/tiddlers directorytiddlywiki ~/MyWiki --rendertiddler $:/core/save/all index.html text/plainMaking a translation
Prerequisites:
Quick and dirty instructions:
/MyTranslation/TiddlyWiki5)/MyTranslation/jermolene.github.com<repo>/languages for your translation<repo>/core/language/en-GB into your translation folderplugin.info file (see below) in your translation folder<repo>/editions/tw5.com/tiddlywiki.info to add your language to the list./qbld.sh to build TiddlyWiki/MyTranslation/jermolene.github.com/index.html.tid and .multids files in your language folder to translate the English textContent of plugin.info for Joe Bloggs' Welsh translation:
{
"title": "$:/languages/cy-GB",
"name": "cy-GB",
"plugin-type": "language",
"description": "Welsh (British)",
"author": "JoeBloggs",
"core-version": ">=5.0.0"
}MultiTiddlerFiles make it possible to pack the text of several tiddlers in a single text file, simplifying some editing tasks.
The recommended technique for building TiddlyWiki plugins involves running TiddlyWiki on Node.js, but there is now an experimental technique for creating plugins directly in the browser.
Loading a plugin in the browser has several consequences:
To make a modified copy of a plugin, one edits the constituent shadow tiddlers (doing this actually overrides the shadow tiddler with a new non-shadow tiddler containing the modified content). The repacking process retrieves the current value of all the shadow tiddlers included in the plugin, and then bundles the new values back into the original plugin tiddler.
Start with a blank TiddlyWiki. It is useful to create a HelloThere tiddler that contains links to various tiddlers that you'll be opening frequently during plugin development:
$:/plugins/yourname/pluginname)$:/plugins/yourname/pluginname/mywidget.js)Click the link to the plugin tiddler to open it. Assuming it doesn't currently exist, it will open with an italicised title, indicating that it is a missing tiddler. Then switch to edit mode and set the following fields on the tiddler:
| Field | Value |
|---|---|
| dependents | Space separated list of dependent plugins (use square brackets for titles containing spaces) |
| description | Plugin description |
| plugin-type | Either "plugin" for a regular plugin, "theme" for a theme, or "language" for a language pack |
| type | Set to "application/json" |
| version | Set to the version number of the plugin (eg "0.0.1") |
Then in the body of the tiddler, insert:
{"tiddlers": {}}Save the plugin tiddler
Create the payload tiddlers by clicking on the links in the HelloThere tiddler from step 1.
Open the browser developer console, and type the following JavaScript statement, but first change the first parameter to the name of your plugin. The second parameter is an optional array of tiddler titles to be added to the plugin:
$tw.utils.repackPlugin("$:/plugins/yourname/pluginname",["$:/plugins/yourname/pluginname/mywidget.js"])You should see a confirmation message, and then if you inspect the plugin tiddler you should see that it has been filled with the payload tiddlers.
Each time you save the plugin the last portion of the version number is automatically incremented. This will ensure that users with an older version of your plugin will be able to install the new version.
Once you've built the plugin for the first time you can omit the second parameter to repackPlugin() unless you are adding a new tiddler:
$tw.utils.repackPlugin("$:/plugins/yourname/pluginname")To remove tiddlers from the plugin specify their titles in the optional third parameter:
$tw.utils.repackPlugin("$:/plugins/yourname/pluginname",null,["$:/plugins/yourname/pluginname/mywidget.js"])Before attempting to repack your plugin you should ensure that the plugin is selected as the current theme or language. Otherwise the shadow tiddlers will not be present.
HTML tags and comments can be used directly in WikiText. For example:
<article class="hello">
This is my nice and simple block of text. HelloThere
<!-- This comment will not appear in the wikified output -->
</article>Attributes in HTML tags can be specified as a transclusion or a macro invocation. For example, here the value of the href attribute will be set to the value of the tiddler MyLinkDestination:
<a href={{MyLinkDestination}}>link</a>Here an attribute is specified as a macro invocation:
<a href=<<MyMacro "Brian">>>link</a>Literal attribute values can include line breaks. For example:
<div data-address="Mouse House,
Mouse Lane,
Rodentville,
Ratland."/>By using triple-double quotes you can specify attribute values that include single double quotes. For example:
<div data-address="""Mouse House,
"Mouse" Lane,
Rodentville,
Ratland."""/>The content of an HTML element will be parsed in inline mode unless the opening tag is followed by two linebreaks. (Inline mode means that block mode formatting such as tables, lists and headings is not recognised).
Images can be included in WikiText with the following syntax:
[img[Motovun Jack.jpg]]
[img[http://tiddlywiki.com/favicon.ico]]If the image source is the title of an image tiddler then that tiddler is directly displayed. Otherwise it is interpreted as a URL and an HTML <img> tag is generated with the src attribute containing the URL.
A tooltip can also be specified:
[img[An explanatory tooltip|Motovun Jack.jpg]]Attributes can be provided to specify CSS classes and the image width and height:
[img width=32 [Motovun Jack.jpg]]
[img width=32 class="tw-image" [Motovun Jack.jpg]]Note that attributes can be specified as transclusions or variable references:
[img width={{!!mywidth}} class=<<image-classes>> [Motovun Jack.jpg]]The image syntax is a shorthand for invoking the ImageWidget.
You can also display an image stored in a tiddler by transcluding that tiddler. The disadvantage of this approach is that there is no direct way to control the size of the image.
{{Motovun Jack.jpg}}Renders as:
The image widget displays images that can be specified as a remote URL or the title of a local tiddler containing the image.
Any content of the <$image> widget is ignored.
| Attribute | Description |
|---|---|
| source | The URL of the image, or the title of an image tiddler |
| width | The width of the image as a number |
| height | The height of the image |
| tooltip | The tooltip to be displayed over the image |
| class | CSS classes to be assigned to the <img> element |
When used to display tiddler-based images, the image widget operates in two distinct modes:
<img> element and the text field is ignored<img> element that embeds the image data directly using a data: URI.See ExternalImages for more details.
You can import content into a TiddlyWiki file in several ways:
The ImportVariablesWidget imports macro and variable definitions from a list of other tiddlers and makes them available to its children. For example:
<$importvariables filter="[tag[mySpecialMacros]]">
All the macros defined in tiddlers with the tag "mySpecialMacros" are available here
</$importvariables>The content of the importvariables widget is the scope within which the imported variable definitions are available.
| Attribute | Description |
|---|---|
| filter | Tiddler filter defining the tiddlers from which macro definitions will be imported |
So-called global macros are implemented within the main page template ($:/core/ui/PageTemplate) by wrapping the page content in the following importvariables widget:
<$importvariables filter="[[$:/core/ui/PageMacros]] [all[shadows+tiddlers]tag[$:/tags/Macro]!has[draft.of]]">
...
</$importvariables>Initialise an empty WikiFolder with a copy of the specified edition.
--init <edition> [<edition> ...]For example:
tiddlywiki ./MyWikiFolder --init emptyNote:
includeWikis definitions in the edition's tiddlywiki.info filetiddlywiki.info file will be copied from the last edition)--help editions returns a list of available editionsSee also:
npm install -g tiddlywikiIf it fails with an error you may need to re-run the command as an administrator:
npm install -g tiddlywiki(Windows)
sudo npm install -g tiddlywiki(Mac/Linux)
tiddlywiki --version
5.0.8-beta; you may also see other debugging information reported)tiddlywiki mynewwiki --init server to create a folder for a new wiki that includes server-related componentstiddlywiki mynewwiki --server to start TiddlyWikiThe -g flag causes TiddlyWiki to be installed globally. Without it, TiddlyWiki will only be available in the directory where you installed it.
A slightly different method for installation is recommended if you plan on forking the source code in order to study it or contribute to it. See Working with the TiddlyWiki5 repository.
This brief introduction shows how to install and use TiddlyDesktop:
A step by step introduction to how TiddlerFilters are used.
You can experiment with tiddler filters by typing them into the "Filter" tab of the advanced search panel.
The simplest example of a filter is a list of tiddler titles (if necessary quoted with double square brackets):
HelloThere Introduction [[Title with Spaces]]The titles must be separated by one or more spaces and/or linebreaks.
Filter operators are used to select tiddlers based on some criteria. For example, this filter consists of a single operation that selects all tiddlers tagged "introduction":
[tag[introduction]]The word "tag" is the operator and "introduction" is the operand.
See TiddlerFilters for a complete list of the available operators.
The operator defaults to title if omitted, so [[HelloThere]] is equivalent to [title[HelloThere]]. If there are no spaces in the title, then the double square brackets can also be omitted: HelloThere.
Filter operations can be negated by preceding the operator with an exclamation mark (!). This example selects all tiddlers that are not tagged "introduction":
[!tag[introduction]]Some filter operators can take an optional suffix that provides further information for the operation. For example, the "field" operator takes a suffix indicating the field to be compared. The following filter returns all tiddlers that have "JeremyRuston" in the "modifier" field:
[field:modifier[JeremyRuston]]If an unknown operator is used then it is instead interpreted as the suffix of the "field" operator. Thus, these two filters both return all the tiddlers that contain the string "create" in their "caption" field:
[caption[create]]
[field:caption[create]]If a filter operator is written with curly brackets around the operand then it is taken to be a TextReference to the actual value. For example, this filter selects all tiddlers containing the string contained in the tiddler titled "$:/temp/search"
[search{$:/temp/search}]The "field" filter also accepts regular expressions with the syntax /regexp/(modifier). For example:
[field:title/example/]: searches for all tiddlers having "example" in their title[field:title/example$/]: $ is an "anchor" for the end of the text so that "example" has to be at the end of the title[field:text/summer|winter/(i)]: Searches for tiddlers containing "summer" or "winter", ignoring caseYou can use multiple filter operations at once. This example selects all tiddlers that are either tagged "introduction" or "demo":
[tag[introduction]] [tag[demo]]Each separate operator is processed in turn, accumulating the tiddlers that they select.
A sequence of operators can be logically ANDed together by bashing them together and merging the outer square brackets. This is called a "run" of operations. For example, here we select tiddlers that are tagged "introduction" and also tagged "demo":
[tag[introduction]tag[demo]]Here's another example that selects all tiddlers tagged "introduction" that are not tagged "demo":
[tag[introduction]!tag[demo]]Ordinarily, each run of filter operations adds to the accumulated results. Prefixing a run with - causes the list of tiddlers to instead be removed from the results. For example, this example returns all the tiddlers tagged "introduction" apart from HelloThere and Title with Spaces:
[tag[introduction]] -HelloThere -[[Title with Spaces]]This example returns all tiddlers tagged "introduction" that are not also tagged "demo":
[tag[introduction]] -[tag[demo]]Usually, each run of filter operations takes as its source the entire store of available tiddlers. Prefixing a run with + causes the accumulated results to be used as the source instead.
For example, this filter selects tiddlers tagged "introduction" or "demo" and then sorts the resulting list by the "title" field:
[tag[introduction]] [tag[demo]] +[sort[title]]JavaScript is a computer language that was originally introduced by browsers as a way of scripting web pages. At first it was considered a poorly designed toy, but over the years has become recognised as a powerful language in its own right, and has been adopted widely beyond the browser.
JavaScript looks like this:
function circleArea(radius) {
return radius * 2 * 3.141592653;
}Macros can be implemented as JavaScript modules as well as via the wikitext syntax.
JavaScript macros are modules with their module-type field set to macro. They must export these three properties:
this points to the widget node invoking the macro.Note that if the params array is missing or blank, then all the supplied parameters are passed to the run() method.
There are several JavaScript macros built into the core which can serve as a jumping off point for your own macros:
https://github.com/Jermolene/TiddlyWiki5/tree/master/core/modules/macros
Note that JavaScript macros work on both the client and the server, and so do not have access to the browser DOM.
Macros are just used to return a chunk of wikitext for further processing. They should not make modifications to tiddlers in the wiki store. The reason is that you cannott control when the macro is called; it may be called repeatedly as part of refresh processing. So it is important that macros do not have any other side effects beyond generating their text.
I'm the inventor of TiddlyWiki. I am available through my company FederatialLimited for consultancy and speaking engagements.
You can find me on these services:
Further information:
Keyboard shortcut support is currently very limited but will be improved in later releases.
| Key | Shortcut description |
Ctrl-Enter | Confirm changes to the draft tiddler containing the keyboard focus |
Escape | Abandon changes to the draft tiddler containing the keyboard focus |
The keyboard widget allows WidgetMessages to be generated in response to key presses.
The content of the <$keyboard> widget is rendered normally. The keyboard shortcut only takes effect within the contained content.
| Attribute | Description |
|---|---|
| message | The title of the WidgetMessage to generate |
| param | The parameter to be passed with the WidgetMessage |
| key | Key string identifying the key to be trapped (see below) |
| class | A CSS class to be assigned to the generated HTML DIV element |
Key strings are made up of zero or more of the modifiers alt, shift or ctrl followed by the name of a key, all joined with "+" plus symbols. Key names are either the letter or digit printed on the key (eg "a" or "1"), or one of the special keys backspace, tab, enter or escape.
For example:
A
shift+A
shift+escape
ctrl+enter
ctrl+shift+alt+AThe latest news, articles, resources and examples.
Matabele's stylish and clean system for personal task management.
This is my work in progress version of TW5, incorporating various features and ideas as and when they intrigue me. To grab any feature you may wish to try, drag the listed tiddlers across to the dropzone of an empty TiddlyWiki 5.0.10-beta
A collection of TiddlyWiki resources from Mario Pietsch, with a focus on cloud deployments. Mario also maintains the German translation of TiddlyWiki.
My name is Mario Pietsch from Austria. I'm living near Salzburg.
This page, will be the portal to my TiddlyWiki, TiddlyWeb related content.
An experimental MathJax plugin for TiddlyWiki version 5. As Martin says, the implementation is a bit of a hack but may be useful until we have a better alternative.
Welcome. I have created plugin for TiddlyWiki 5 which allows you to use MathJax (math in TeX and MathML) inside TiddlyWiki 5. It's unofficial plugin and it doesn't follow general policy of TiddlyWiki as stand-alone solution but it works. So you can use it if you want.
Notes and tips by a developer working on writing TiddlyWiki plugins – including TWExe, a widget for running Windows scripts and executables.
A translation of the tiddlywiki.com documentation from Bram Chen, TiddlyWiki's Chinese translator.
Huge collection of customisations and tweaks from Ton Gerner.
I am a longtime user of TiddlyWiki Classic and still use it daily since you can't do everything in TiddlyWiki 5 (yet) ;)
I started experimenting with TW5 at the end of September 2013 (alpha10). Since I missed a few things in the layout I got used to in TiddlyWiki Classic 1, I started with modifying the layout of TW5. To share my knowledge, I made a few guides about these 'modifications'. The guides started as a non-linear personal web notebook (yeah, the subtitle of TiddlyWiki!). I started experimenting with layout things and used TW5 to document my experiments.
Chris Hunt's detailed developer tutorials for getting started with writing widgets for TiddlyWiki.
These pages document aspects TiddlyWiki5 programming, sharing "lessons learned" to help developers to get started with TiddlyWiki5 customization and extension.
There are currently two articles in this wiki:
- A Simple Widget
- A More Complex Widget
Ordinarily with TiddlyWiki, the full content of all tiddlers is embedded into the main HTML file. Lazy loading refers to the technique of only embedding metadata about the tiddler (in other words all fields except the text field), and requesting the body from the server when required.
Lazy loading can be used in two configurations:
See the LazyLoadingMechanism for details of how lazy loading is implemented.
To run TiddlyWiki with lazy loading for images, use this alternative ServerCommand to start the server:
tiddlywiki --server 8080 $:/core/save/lazy-imagesWith the current configuration, lazy loading is enabled by default.
TiddlyWiki currently only implements LazyLoading when it is running in the browser talking to a TiddlyWeb-compatible server.
In the configuration for TiddlyWeb, the browser first requests a "skinny" version of each tiddler (consisting of all the fields apart from the text field). Subsequently, an attempt to read those skinny tiddlers with wiki.getTiddler() returns just the skinny fields, but an attempt to read one using wiki.getTiddlerText() will trigger an asynchronous load of the full tiddler text, which in turn triggers a refresh cycle, updating the display to reflect the newly loaded tiddler. Widgets that loop through all tiddlers are fine; it's only if they trigger wiki.getTiddlerText() for a tiddler that it will get loaded.
Lazy loading can also be used with TiddlyWiki's own server. The core provides a template that enables images to be lazily loaded while other tiddlers are packaged into the initial HTML file in the usual way.
The browser-based search built into TiddlyWiki5 will only search the text of tiddlers that have been fully loaded. The expectation is that when lazy loading is used in a client-server configuration, then it is the server that really needs to handle search operations, because it is only the server that can "see" the text of all tiddlers. So, the plan is to integrate the built in search with TiddlyWeb's search API. The simplest approach is that any local search triggers an asynchronous server side search. The results of the search would be asynchronously loaded such that they would dynamically appear in the local search results.
The link catcher widget traps WidgetMessage: tw-navigate dispatched within its child content by performing any or all of these actions:
The content of the <$linkcatcher> widget is displayed normally.
| Attribute | Description |
|---|---|
| to | Optional title of the tiddler to be set to the title of the navigated tiddler |
| message | Optional identifier for a widget message to be sent when a navigation is caught |
| set | Optional title of the tiddler to be set to a specified value when navigation occurs |
| setTo | Value to be assigned by the set attribute |
A key capability of WikiText is the ability to make links to other tiddlers or to external websites. There are several ways of doing this:
Link to a tiddler by title:
[[Tiddler Title]]To link to a tiddler and specify the text of the link:
[[Displayed Link Title|Tiddler Title]]For tiddler titles that match the CamelCase rules, just typing the title will automatically create a link.
To link to an external website, type the full URL of the site:
http://tiddlywiki.com/
[[TW5|http://tiddlywiki.com/]]For this syntax to work, the URL has to be recognisable as an URL, including a protocol such as http:// or file://. You can force an external link with the extended syntax:
[ext[tiddlywiki.com]]
[ext[caption for link|tiddlywiki.com]]
[ext[Donate|bitcoin:1aabbdd....?amount=0.001]]You can suppress a link from being recognised by preceding it with ~. For example:
The link widget generates links to tiddlers.
| Attribute | Description |
|---|---|
| to | The title of the target tiddler for the link (defaults to the WidgetVariable: currentTiddler) |
| aria-label | Optional Accessibility label |
| tooltip | Optional tooltip WikiText |
The content of the link widget is rendered within the <a> tag.
The default value of the tooltip attribute is <<tw-wikilink-tooltip>>.
This means that you can control the text of a link tooltip in several ways:
<$link to="HelloThere" tooltip="Custom tooltip">Link 1</$link>
<$set name="tw-wikilink-tooltip" value="I'm a link to {{!!title}}">
<$link to="HelloThere">Link 2</$link>
</$set>
Renders as:
Note that the tooltip is rendered with the current tiddler set to the target of the link.
A useful convention is to set the tooltip like this:
\define tw-wikilink-tooltip()
<$transclude field="tooltip"><$transclude field="title"/></$transclude>
\endThis causes the tooltip to be the tooltip field of the target tiddler. If the field isn't present, then the title is used instead.
tw-tiddlylink - applied to all linkstw-tiddlylink-external - applied to external, non-tiddler linkstw-tiddlylink-internal - applied to tiddler linkstw-tiddlylink-missing - applied to tiddler links where the target tiddler doesn't existtw-tiddlylink-resolves - applied to tiddler links when the target tiddler does existConfiguration macros can be used to modify the behaviour of the link widget.
Links are suppressed if the macro tw-wikilinks evaluates to the string no. For example:
\define tw-wikilinks() noThe target of the link widget defaults to the URL encoded title of the tiddler. The href can be templated by defining the configuration macro tw-wikilink-template, and including within it the token $uri_encoded$. For example:
\define tw-wikilink-template() http://tiddlywiki.com/#$uri_encoded$The token $uri_doubleencoded$ is replaced by the double encoded title of the tiddler.
Note that in the browser the <a> element generated by the link widget has a JavaScript event handler that navigates directly to the target tiddler, ignoring the href attribute.
Provides default text for the link tooltip:
\define tw-wikilink-tooltip() This is a link to {{!!title}}
<$link to="HelloThere"/>The list field of a tiddler is an optional feature that can be used to help structure your content. It is defined as an ordered sequence of tiddler titles, and it can be used in several ways:
list field of a tiddler that is being used as a tag determines the ordering of the tiddlers that carry that tag - see TiddlerTags for detailslist filter selects the entries from a listlisted filter selects the tiddlers that list the selected tiddler(s)list field of the tiddlers that are displayed in the main story columnYou can create unordered lists with * characters:
Ordered lists use # instead of *:
You can also mix ordered and unordered list items:
You can also assign a CSS class to an individual member of a list with this notation:
Note that Block Quotes in WikiText can be mixed with lists. For example:
The list widget displays a sequence of tiddlers that match a tiddler filter. It can be used for many purposes:
The tiddlers can either be displayed by transcluding each in turn through an optional template.
The content of the <$list> widget is an optional template to use for rendering each tiddler in the list (alternatively, the template can be specified as a tiddler title in the template attribute).
| Attribute | Description |
|---|---|
| filter | The TiddlerFilter to display |
| template | The title of a template tiddler for rendering each tiddler in the list |
| editTemplate | An alternative template to use for DraftTiddlers in edit mode |
| variable | The widget variable name to be assigned the title of each tiddler in the list. Defaults to currentTiddler |
| emptyMessage | Message to be displayed when the list is empty |
| storyview | Optional name of module responsible for animating/processing the list |
| history | The title of the tiddler containing the navigation history |
The <$list> widget can optionally render draft tiddlers through a different template tiddler than ordinary tiddlers – see DraftMechanism for a discussion of how this capability is used.
storyview attributeThe storyview attribute specifies the name of an optional module that can animate changes to the list (including navigation). The core ships with the following storyview modules:
classic: renders the list as an ordered sequence of tiddlerszoomin: just renders the current tiddler from the list, with a zoom animation for navigating between tiddlerspop: shrinks items in and out of placeThe optional history attribute specifies the name of a tiddler that is used to track the current tiddler for navigation purposes. When the history tiddler changes the list view responds by telling the listview to handle navigating to the new tiddler. See the NavigationMechanism for more details.
The types and recent tabs in the sidebar give two examples of a grouped list created by nesting.
The types listing is performed with this markup:
<$list filter="[!is[system]has[type]each[type]sort[type]]">
<div class="tw-menu-list-item">
<$view field="type"/>
<$list filter="[type{!!type}!is[system]sort[title]]">
<div class="tw-menu-list-subitem">
<$link to={{!!title}}><$view field="title"/></$link>
</div>
</$list>
</div>
</$list>
The outer list filter selects each discrete value found in the type field. The inner list filter selects all the (non-system) tiddlers with that type.
The recent listing is performed with this markup:
<$list filter="[!is[system]has[modified]!sort[modified]limit[100]eachday[modified]]">
<div class="tw-menu-list-item">
<$view field="modified" format="date" template="DDth MMM YYYY"/>
<$list filter="[sameday{!!modified}!is[system]!sort[modified]]">
<div class="tw-menu-list-subitem">
<$link to={{!!title}}><$view field="title"/></$link>
</div>
</$list>
</div>
</$list>Here the outer list filter selects each discrete day found in the modified field, while the inner list filter selects all the tiddlers dated the same day in the modified field.
Load tiddlers from 2.x.x TiddlyWiki files (.html), .tiddler, .tid, .json or other files
--load <filepath>To load tiddlers from an encrypted TiddlyWiki file you should first specify the password with the PasswordCommand. For example:
tiddlywiki ./MyWiki --password pa55w0rd --load my_encrypted_wiki.htmlNote that TiddlyWiki will not load an older version of an already loaded plugin.
The macro call widget provides an alternative syntax for invoking macros. The advantage of the widget form is that it allows macro parameters to be specified as widget attributes, thus allowing indirection and macro values to be set.
For example, a macro called italicise that takes a single parameter called text can be invoked in any of these ways:
<<italicise "Text to be made into italics">>
<<italicise text:"Text to be made into italics">>
<$macrocall $name="italicise" text="Text to be made into italics"/>
<$macrocall $name="italicise" text={{Title of tiddler containing text to be italicised}}/>
<$macrocall $name="italicise" text=<<textMaker "Another macro to generate the text to be italicised">>/>You can see several examples of the macro call widget within the core:
data: URIs: $:/themes/tiddlywiki/starlight/styles.tidThe content of the <$macrocall> widget is ignored.
| Attribute | Description |
|---|---|
| $name | Name of the macro to invoke |
| $type | ContentType with which the macro text should be parsed (defaults to text/vnd.tiddlywiki) |
| $output | ContentType for the output rendering (defaults to text/html, can also be text/plain) |
| parameters | Macro parameters specified as attributes |
Macros are snippets of text that can be inserted with a concise shortcut:
<<myMacro>>You can write your own Macros in WikiText or for more flexibility you can write JavaScript Macros.
Macros are snippets of text that can be inserted with a concise shortcut.
Multi-line macros are defined like this:
\define mysamplemacro(name:"Bugs Bunny",address:"Rabbit Hole Hill")
Hi, I'm $name$ and I live in $address$
\endThe first line of the definition specifies the macro name and any parameters. Parameters are named and can optionally have default values that are used if the parameter isn't specified at the time of calling. The body of the macro definition follows, terminated with \end. The macro can include parameters using the $name$ construction.
Single-line macros can omit the \end marker like this:
\define mysamplemacro(name:"Bugs Bunny") Hi, I'm $name$Macro definitions must be placed at the top of a tiddler. Macros are available to the tiddler that defines them, plus any tiddlers that it transcludes.
Global macros can be defined in any tiddler with the tag $:/tags/Macro. They are then available within all tiddlers.
Macros can be imported from other tiddlers with the ImportVariablesWidget.
JavaScript Macros can also be used for more flexibility.
Macros are used like this:
<<mysamplemacro>>
<<mysamplemacro "Donald Duck">>
<<mysamplemacro "Mickey Mouse" "Mouse House">>Resulting in:
Hi I'm Bugs Bunny and I live in Rabbit Hole Hill
Hi I'm Donald Duck and I live in Rabbit Hole Hill
Hi I'm Mickey Mouse and I live in Mouse House
Parameters can include line breaks. For example:
<<mysamplemacro "Mickey Mouse" "Mouse House,
Mouse Lane,
Rodentville,
Ratland.">>By using triple-double quotes you can specify parameter values that include single double quotes. For example:
<<mysamplemacro "Mickey Mouse" "Mouse House,
"Mouse" Lane,
Rodentville,
Ratland.""">>The makedatauri macro constructs a data URI from a block of text and an associated ContentType. It is commonly used within stylesheets to generate an inline image or font.
| Position | Name | Description | Default |
|---|---|---|---|
| 1st | text | Text to be converted to a data URI | |
| 2nd | type | ContentType of text |
A trivial example to show how the macro works:
<<makedatauri "HelloThere" "text/plain">>A user-defined macro such as this would typically be used within a stylesheet:
\define datauri(title)
<$macrocall $name="makedatauri" type={{$title$!!type}} text={{$title$}}/>
\endThen one can write CSS rules like this:
background: url(<<datauri "$:/themes/tiddlywiki/starlight/ltbg.jpg">>);This demo shows how to use SVG to render transcluded text along a path. Enter some text in the textbox below to try it out; view the source to see how it is done.
An experimental MathJax plugin for TiddlyWiki version 5. As Martin says, the implementation is a bit of a hack but may be useful until we have a better alternative.
Welcome. I have created plugin for TiddlyWiki 5 which allows you to use MathJax (math in TeX and MathML) inside TiddlyWiki 5. It's unofficial plugin and it doesn't follow general policy of TiddlyWiki as stand-alone solution but it works. So you can use it if you want.
MathML is a markup language for mathematical notation that can be used with HTML.
If your browser supports it, MathML elements can be used in TiddlyWiki5 WikiText just like HTML.
Here is an example MathML equation from the W3C:
<math><mrow><mo>[</mo><mtable><mtr><mtd><mn>0</mn></mtd><mtd><mn>1</mn></mtd><mtd><mn>0</mn></mtd></mtr><mtr><mtd><mn>0</mn></mtd><mtd><mn>0</mn></mtd><mtd><mn>1</mn></mtd></mtr><mtr><mtd><mn>1</mn></mtd><mtd><mn>0</mn></mtd><mtd><mn>0</mn></mtd></mtr></mtable><mo>]</mo></mrow></math>Renders as:
A module in TiddlyWiki5 is a tiddler containing executable JavaScript, of the type application/javascript and with the field module-type set to the ModuleType of the module.
See the Internals tab of the control panel for lists of the currently loaded modules.
The module-type field of a JavaScript module is a string that identifies the type of the module.
See the Internals tab of the control panel for a list of the module types used in this wiki.
MultiTiddlerFiles allow multiple tiddlers to be concisely represented in a single text file.
The goals of this format are:
MultiTiddlerFiles have the extension multids. The file is structured as a block of shared fields followed by a blank line. The rest of the file is a sequence of comments and tiddlers. Tiddlers are specified by their title, followed by a colon, at least one space character, and then the rest of the line is the text field for the tiddler.
For example:
title: $:/language/ControlPanel/
tags: strings
modifier: JoeBloggs
Basics/Caption: Basics
# This is a comment
Basics/Version: ~TiddlyWiki VersionThis example defines two tiddlers, $:/language/ControlPanel/Basics/Caption and $:/language/ControlPanel/Basics/Version.
If a title field is specified in the header then it is treated as a prefix for the individual tiddlers defined in the title.
The system tiddlers provided as part of the core are named according to the following rules:
| Namespace | Format | Description |
|---|---|---|
$:/* | CamelCase | Root user interface tiddlers (eg control panel, advanced search) |
$:/config/* | CamelCase | User-oriented configuration setting |
$:/core/images/* | hyphen-case | Core images |
$:/core/modules/* | lowercase | JavaScript module tiddlers |
$:/core/save/* | lowercase | Saving templates for creating TiddlyWiki documents |
$:/core/templates/* | inconsistent | Templates needed for TiddlyWiki to operate. Currently uses a mix of dashes and periods to separate words |
$:/core/ui/* | inconsistent | Tiddlers comprising the default user interface of TiddlyWiki. Currently uses a mix of CamelCase and lowercase naming conventions |
$:/core/wiki/* | lowercase | Metadata about the entire wiki |
$:/docs/* | lowercase | Documentation tiddlers |
$:/messages/* | CamelCase | System messages |
$:/plugins/* | lowercase | Plugin tiddlers, and plugin content |
$:/snippets/* | inconsistent | Reusable snippets (will be replaced by macros) |
$:/state/* | lowercase | User interface state tiddlers |
$:/tags/* | CamelCase | User interface configuration tags (currently $:/tags/stylesheet is inconsistent) |
$:/temp/* | lowercase | Temporary tiddlers that shouldn't be saved |
$:/themes/* | lowercase | Theme plugins |
The tiddler $:/view is inconsistently named and should be renamed $:/config/View
In the format column:
The navigator widget manipulates the current store, the story list and history lists in response to various WidgetMessages.
The navigator widget displays any contained content, and responds to WidgetMessages dispatched within it.
| Attribute | Description |
|---|---|
| story | Name of the tiddler containing the story list to be manipulated |
| history | Name of the tiddler containing the history list to be manipulated |
The following WidgetMessages are handled by the navigator widget:
node-webkit is an OpenSource application that fuses the functionality of a web browser with that of Node.js. It makes it possible to use web applications as though they were native apps, with full access to the file system and other native facilities. Learn more from the official site or this introductory blog post.
See TiddlyWiki on node-webkit for details of how to use TiddlyWiki with node-webkit.
Node.js is a downloadable application for your PC, Mac or Linux computer that lets it run JavaScript applications. Unlike JavaScript applications running in a web browser, Node.js code has full access to the file system and other resources of the computer, enabling it to perform the roles that have traditionally been the preserve of languages like Java, PHP and Python. See http://nodejs.org for more details.
For TiddlyWiki, Node.js means that we can have a single code base that can run in the browser or on the server, giving great flexibility in how it is used.
For end users, Node.js is no more complicated to install than a web browser, but unlocks powerful capabilities such as the ability to run TiddlyWiki as a web server that you can connect to from other devices.
See TiddlyWiki on Node.js for more details.
Version 5.0.11-beta includes some changes that can break content from earlier releases of TiddlyWiki 5.
Previously, commands that generate output files would interpret the specified path to the file as being relative to the current working directory. So, for example, the following command would write index.html to the current directory:
tiddlywiki mywiki --rendertiddler $:/core/save/all index.html text/plainIn 5.0.11-beta this behaviour has changed, and now the specified filename is resolved relative to an output folder within the TiddlyWikiFolder. So the command above will now write the file index.html to mywiki/output/index.html.
You can override this behaviour with the OutputCommand. For example, to generate the index.html file within the current directory:
tiddlywiki mywiki --output . --rendertiddler $:/core/save/all index.html text/plainA further change is that the --rendertiddlers command now clears the output folder before it writes any files. This means that any previous --rendertiddler commands to the same folder will have their output deleted.
Version 5.0.8-beta includes some changes that can break content from earlier releases of TiddlyWiki 5.
You should rename any existing SiteTitle and SiteSubtitle tiddlers to $:/SiteTitle and $:/SiteSubtitle respectively.
Version 5.0.8-beta marks a change in the way that TiddlyWiki determines whether to parse the content of an HTML element or widget in block mode or inline mode.
<p> tags to wrap them. It also recognises block syntax like headings, lists and tables.It's important to be able to control which type of parsing is performed for different situations.
Prior to 5.0.8-beta, TiddlyWiki parsed the content of an element in inline mode unless the opening tag of the element were immediately followed by a line break. This meant that much of the time element tags would be shunted together into a long line, hindering readability.
The new behaviour for 5.0.8-beta is to parse the content of an element in inline mode unless the opening tag is immediately followed by two line breaks.
To adjust existing content for 5.0.8-beta you will need to manually add the additional line break after the opening tag of elements and widgets whose content should be parsed in block mode.
The positive aspect of the change is that it removes the need to pack multiple HTML tags onto a single line, improving readability.
Consider the difference between these two examples. First, here's an HTML tag that starts with two line breaks:
Secondly, here's an HTML tag with just a single line break. Notice how the heading is no longer recognised as a heading
The handling of wiki folders has changed. Previously, if the tiddlywiki command was run against a wiki folder that didn't have the necessary tiddlywiki.info file then it would be automatically created. Now, the wiki folder must be initialised with the InitCommand.
This is how to create and start a new server-based wiki:
tiddlywiki mywikifolder --init server
tiddlywiki mywikifolder --serverNote that the name of the clientserver edition has changed to server.
OpenSource is defined by Wikipedia as a philosophy, or pragmatic methodology that promotes free redistribution and access to an end product's design and implementation details.
Founded in 2004 by JeremyRuston, Osmosoft was originally a consultancy for software services around TiddlyWiki. Notable engagements included working with Socialtext on Socialtext Unplugged.
In 2007, Osmosoft was acquired by BT and became the champions for open source within the enterprise. As part of BT, Osmosoft has worked on a diverse range of projects within BT and for BT's customers.
Sets the base output directory for subsequent commands. The default output directory is the output subdirectory of the edition directory.
--output <pathname>If the specified pathname is relative then it is resolved relative to the current working directory.
The Oxford TiddlyWiki Interest Group meets monthly for discussions and demonstrations about TiddlyWiki.
See https://oxtwig.eventbrite.co.uk/ for details of our next meeting.
We have an email discussion list, too: https://groups.google.com/forum/#!members/oxtwig
The second OXTWIG meeting was held on Thursday 16th January 2014:
The first OXTWIG meeting was held on Thursday 21st November 2013:
{
"name": "tiddlywiki",
"main": "./index.html",
"window": {
"toolbar": true,
"width": 1024,
"height": 768
}
}To mark the end of a paragraph in TiddlyWiki you need to type enter twice to create a double line break:
This is the first paragraph.
And this is the second paragraph.Single line breaks are ignored within paragraphs. For example:
For situations where this behaviour isn't convenient, you can also use Hard Linebreaks in WikiText.
The parsing mechanism analyses the text of a tiddler against a set of parsing rules, producing a tree representing the structure of the text. The RenderingMechanism is used to transform parse trees into render trees of widget nodes.
TiddlyWiki5 includes ParserModules for several types of tiddler:
The WikiText parser is the most complex, comprising separate individual WikiRuleModules encapsulating each parsing rule.
The output of parsing a tiddler is an object containing a tree of parse nodes corresponding to the original text. For example:
> JSON.stringify($tw.wiki.parseText("text/vnd.tiddlywiki","Some //italics// and a {{Transclusion}}.").tree)
[
{type: "element", tag: "p", children: [
{type: "text", text: "Some "},
{type: "element", tag: "em", children: [
{type: "text", text: "italics"}
]},
{type: "text", text: " and a "},
{type: "tiddler", attributes:{
tiddler: {type: "string", value: "Transclusion"}
}, children:[
{type: "transclude", attributes:{
tiddler: {type: "string", value: "Transclusion"}
}}
]},
{type: "text", text: "."}
]}
]Parse tree nodes are plain JavaScript objects, and do not have a prototype.
The password widget displays a password input box that is bound to a named entry in the TiddlyWiki5 PasswordVault. Passwords are currently stored in the browsers local storage and are not themselves encrypted.
The content of the <$password> widget is ignored.
| Attribute | Description |
|---|---|
| name | Name of the password vault entry |
Permalinks allow direct links to individual tiddlers within a TiddlyWiki.
The simplest form of permalink is a single target tiddler title appended to the base URL with #:
http://tiddlywiki.com/#HelloThere
The tiddler title can contain spaces if required:
http://tiddlywiki.com/#Using TiddlyWiki on Node.js
Note that double square brackets are not required around the target tiddler title; however, if present they are silently removed.
The permalink can also specify the story list of tiddlers that should be opened alongside the target tiddler as a TiddlerFilter:
http://tiddlywiki.com/#TiddlerFields:Tiddlers TiddlerTags TiddlerFields ContentType
If the target tiddler isn't present in the story list then it is automatically inserted at the top. This means that the following two examples both target the tiddler Tiddlers within the story sequence Tiddlers, Tags, TiddlerFields:
http://tiddlywiki.com/#Tiddlers:Tags TiddlerFields
http://tiddlywiki.com/#Tiddlers:Tiddlers Tags TiddlerFields
It is also possible to specify a story filter without specifying a target tiddler for navigation:
http://tiddlywiki.com/#:[tags[task]]
There are technical restrictions on the legal characters in an URL fragment. To allow all tiddler titles to be addressed, illegal characters are subject to a process called "URL encoding" whereby problematic characters are replaced by their numeric code. For example, the space character is replaced with %20.
Both the target tiddler title and the story filter should be URL encoded (but not the separating colon). TiddlyWiki generates properly encoded URLs which can look quite ugly. However, in practice browsers will usually perfectly happily process arbitrary characters in URL fragments. Thus when creating permalinks manually you can choose to ignore URL encoding.
Two important aspects of TiddlyWiki's behaviour with permalinks can be controlled via options in the $:/ControlPanel Advanced/Settings tab:
Note that typing or navigating to a permalink will always cause the permalink to be processed, and tiddlers opened and closed as appropriate.
When TiddlyWiki starts up it processes permalinks according to the following steps; the same steps are repeated if the permalink changes dynamically (this happens in response to the user editing the address bar, for example).
TiddlyWiki is an opinionated tool, but the opinions are in the domain of philosophy rather than of implementation, where it is infinitely customisable.
The purpose of recording and organising information is so that it can be used again. The value of recorded information is directly proportional to the ease with which it can be re-used.
The philosophy of tiddlers is that we do this by slicing information up into the smallest semantically meaningful units with rich modelling of relationships between them. Then we use aggregation and composition to weave the fragments together to present narrative stories.
TiddlyWiki aspires to provide an algebra for tiddlers, a concise way of expressing and exploring the relationships between items of information.
Plugins are bundles of tiddlers that are distributed and managed as a single unit by being packed into a single JSON tiddler. If a tiddler isn't found in the main store, then the registered plugins are searched for it instead.
Tiddlers within plugins behave something like shadow tiddlers in classic TiddlyWiki: they can be freely overwritten by creating a tiddler with the same title, but deleting that tiddler restores the underlying tiddler value from the plugin.
Plugins have a plugin-type field that may be:
plugin (default) - a plain plugintheme - a theme plugin (see ThemeMechanism)Plugins can be used to package ordinary content, or can include JavaScript modules that extend and enhance the core TiddlyWiki5 functionality.
Plugins conventionally have a title of the form $:/plugins/publisher/name. Plugins that are part of the core TiddlyWiki distribution have titles of the form $:/plugins/tiddlywiki/name.
Plugins that define macros, views or other named entities are expected to prefix the name with their publisher identifier, for example: tiddlytools.slider.
Plugins are stored as tiddlers with the following fields:
| Field | Description |
|---|---|
| title | Title of plugin |
| description | Description of plugin |
| author | Author of plugin |
| version | Version string (must conform to SemanticVersioning convention) |
| source | Source URL of plugin |
| type | Must be application/json |
| plugin-type | Can be plugin (default) or theme |
| text | JSON encoding of the list of tiddlers comprising the plugin |
| dependents | List of dependent plugins (currently only implemented for themes) |
On the server, plugins can be stored as ordinary JSON tiddlers but it is often more convenient to store them as separate tiddler files within folders. Plugin folders must contain a plugin.info file that contains the metadata for the plugin. It can also optionally identify files external to the plugin folder that should be loaded as tiddlers.
The plugin.info file should contain the following JSON structure:
The JSON structure for plugin tiddlers is as follows:
{
"title": "$:/plugins/publisher/name",
"description": "An exemplary plugin for demonstration purposes",
"author": "JeremyRuston",
"version": "1.2.3-alpha3",
"core-version": ">=5.0.0",
"source": "http://tiddlywiki.com/MyPlugin",
"plugin-type": "plugin"
}By convention, the titles of the individual tiddlers are prefixed with the title of the containing plugin, but they are not restricted to do so.
Note that if the version field is omitted from a plugin.info file when the plugin folder is packed then it is automatically filled in by the core to the current core version number. This is to ensure that all the core plugins carry the correct version number. Generally plugin authors will want to ensure that they do explicitly specify a version number.
The standard distribution of TiddlyWiki includes a number of standard plugins in the plugins directory.
To be usable in the browser, plugins just need to be included in the wiki. For wikis that are generated on the server, TiddlyWikiFolders can contain a tiddlywiki.info file that identifies the plugins to be included in this wiki:
{
"plugins": [
"tiddlywiki/slider",
"tiddlytools/chooser"
]
}Plugins names refer to plugin folders listed in TiddlyWiki5's root plugins folder.
Plugins can also be included manually by copying them into the plugins subfolder of the wiki.
The wiki object keeps track of all of the currently loaded plugins. If a request for a tiddler isn't in the store then the wiki looks through the cascade of plugins to find the requested tiddler. It is a similar idea to the way that shadow tiddlers are implemented in classic TiddlyWiki.
In the browser, any constituent tiddlers that are JavaScript modules (ie shadow tiddlers of content type application/javascript and possessing the field module-type) are executed during startup processing.
A plugin in TiddlyWiki5 is a bundle of tiddlers packaged together as a single tiddler. Plugins are used to distribute optional, custom components for TiddlyWiki.
The tiddlers within a plugin appear as ShadowTiddlers.
Plugins can contain JavaScript modules, style sheets, and templates to extend the functionality of TiddlyWiki itself. Plugins can also be used to distribute ordinary text, images or other content. Plugins can be updated from their source as a unit.
See the PluginMechanism discussion for more details about how plugins are implemented internally.
The popup mechanism allows blocks of content to be selectively displayed and positioned with respect to an anchor. It has several parts:
Ordinarily, at startup TiddlyWiki displays the tiddlers specified as a filter in the tiddler $:/DefaultTiddlers.
Sometimes it's useful to re-open the same tiddlers that were open when the file was saved. To do so, set $:/DefaultTiddlers to this filter:
[list[$:/StoryList]]This filter returns the tiddlers specified in the $:/StoryList tiddler, which is the system tiddler that TiddlyWiki uses to store the sequence of tiddlers in the current story.
The qualify macro is part of the StateMechanism. Given a base tiddler title it generates a unique string that includes a hashed encoding of a position within the widget render tree, identified by the stack of transcluded tiddlers that leads to that position.
| Position | Name | Description | Default |
|---|---|---|---|
| 1st | title | Base tiddler title |
The results returned by the qualify macro will depend upon where it is used. For example:
<<qualify "base">>Returns:
base-{-370603839}
Wikipedia defines a Quine as a computer program which takes no input and produces a copy of its own source code as its only output.
TiddlyWiki is an unusual example of a practical quine: it is this ability to produce a copy of its own source code that lies at the heart of TiddlyWiki's ability to independently save changes to itself.
The radio widget displays an HTML <input type="radio"> that reflects whether a given tiddler field has a specified value. Selecting the radio button sets to the tiddler field to the value.
The content of the <$radio> widget is displayed within an HTML <label> element also containing the radio button. This means that clicking on the content will have the same effect as clicking on the button itself.
| Attribute | Description |
|---|---|
| tiddler | Title of the tiddler to manipulate (defaults to the WidgetVariable: currentTiddler) |
| field | The name of the field to which the radio button will be bound |
| value | The value for the tiddler field |
| class | CSS classes to be assigned to the label around the radio button |
This example uses the radio widget to change the modifier field of this tiddler:
<$radio field="modifier" value="JoeBloggs"> Joe Bloggs</$radio>
<$radio field="modifier" value="JaneBloggs"> Jane Bloggs</$radio>It renders as:
Welcome to TiddlyWiki, a complete interactive wiki in JavaScript. It can be used as a single HTML file in the browser or as a powerful Node.js application. It is highly customisable: the entire user interface is itself implemented in hackable WikiText.
This is version 5.0.13-beta of TiddlyWiki, a major reboot designed for the next 25 years. It is currently in beta (see the detailed ReleaseHistory). There is a RoadMap for moving to the full release. It is a great time to get involved and support the future development of TiddlyWiki.
TiddlyWiki is a free, open source project that depends on your love and support for its survival.
Running TiddlyWiki on Node.js brings several important benefits over and above the single file version:
npm install -g tiddlywikiIf it fails with an error you may need to re-run the command as an administrator:
npm install -g tiddlywiki(Windows)
sudo npm install -g tiddlywiki(Mac/Linux)
tiddlywiki --version
5.0.8-beta; you may also see other debugging information reported)tiddlywiki mynewwiki --init server to create a folder for a new wiki that includes server-related componentstiddlywiki mynewwiki --server to start TiddlyWikiThe -g flag causes TiddlyWiki to be installed globally. Without it, TiddlyWiki will only be available in the directory where you installed it.
A slightly different method for installation is recommended if you plan on forking the source code in order to study it or contribute to it. See Working with the TiddlyWiki5 repository.
TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on TiddlyWikiFolders, TiddlerFiles and TiddlyWikiFiles.
For example, the following command loads the tiddlers from a TiddlyWiki HTML file and then saves one of them in static HTML:
tiddlywiki --verbose --load mywiki.html --rendertiddler ReadMe ./readme.htmlRunning tiddlywiki from the command line boots the TiddlyWiki kernel, loads the core plugins and establishes an empty wiki store. It then sequentially processes the command line arguments from left to right. The arguments are separated with spaces.
The first argument is the optional path to the TiddlyWikiFolder to be loaded. If not present, then the current directory is used.
The commands and their individual arguments follow, each command being identified by the prefix --.
tiddlywiki [<wikipath>] [--<command> [<arg>[,<arg>]]]The available commands are:
See also:
If you've installed TiddlyWiki on Node.js on the usual way, when a new version is released you can upgrade it with this command:
npm update -g tiddlywikiOn Mac or Linux you'll need to add sudo like this:
sudo npm update -g tiddlywikiIf you plan on working with the TiddlyWiki5 source code then follow these steps:
npm link (Windows) or sudo npm link (Mac/Linux) to tell npm to use this copy of the repo as the globally installed oneAfter this procedure you can work with TiddlyWiki5 via npm as though it were installed in the usual way with npm install -g tiddlywiki.
See also Scripts for TiddlyWiki on Node.js.
This readme file was automatically generated by TiddlyWiki
This release is the culmination of a large scale refactoring of the widget mechanism of TiddlyWiki5. There are several changes to be aware of if upgrading from earlier versions:
<$setstyle> - use <div style=<<macroName Param>>> instead<$video> - will return in a later release<$datauri> - use the <<makedatauri>> built-in macro instead<$error> - may return in a later release<$import> - use the BrowseWidget, DropzoneWidget and NavigatorWidget instead<$info> - use the <<changecount>> built-in macro instead<$version> - use the <<version>> built-in macro instead<div> or a <span> to be able to style the content<$view format="link"/> is no longer available; use an explicit <$link> widget instead<$view format="link"/> is no longer available; use the TranscludeWidget insteadtiddler is used to reference a tiddler by title, not titlebody element now has the class tw-body, which will need to be specified in any overrides<body> elements in a documentSee GitHub for detailed change history of this release
This minor release just contains fixes for the syncer and related adaptor modules for the TiddlyWeb edition and for TiddlyWiki5's integrated server.
See GitHub for detailed change history of this release
This release has several bug fixes:
<$edit-text> widget<<tabs>> macro to the tiddler info panel, the control panel and the sidebarcaption field for the text of the tab:list field of the corresponding tag tiddlerSee GitHub for detailed change history of this release
This release has several bug fixes:
See GitHub for detailed change history of this release
tw-close-other-tiddlers message (eg, )<$setvariable> to <$set><$setvariable> will temporarily remain as a synonym for <$set> for the next few releasesfields and index attributes of the TranscludeWidgetContributors to this release include @jermolene and @grayeul.
See GitHub for detailed change history of this release
$:/state/tab/sidebar-{$:/core/ui/SideBar|$:/core/ui/SideBar||}{$:/core/ui/PageTemplate|$:/core/ui/PageTemplate||} one gets $:/state/tab/sidebar-{1743827719}$:/tags/PageTemplate$:/core/templates/tiddlywiki5.template.html to $:/core/save/allContributors to this release include @jermolene, @asampal and @pmario.
See GitHub for detailed change history of this release
See GitHub for detailed change history of this release
$:/theme isn't defined or refers to a missing tiddler, then fallback through Snow White to Vanilla. This means that empty.html now defaults to Snow White$:/tags/PageControls tiddlers from being reordered5.0.x-beta and the final release will be 5.1.xSee GitHub for detailed change history of this release
[is[tag]] to the FilterOperator: is[untagged[]] filter operatorSee GitHub for detailed change history of this release
See Notes for upgrading to 5.0.11-beta for more details of these changes:
/output folder within TiddlyWikiFolders (it used to be current directory)[link text](#TiddlerTitle)[ext[tooltip|url]]).tid TiddlerFiles to allow single line text fields$:/ShowEditPreview to $:/state/showeditpreviewI (@Jermolene) would like to thank the contributors to this release who have generously given their time to helping improve TiddlyWiki:
@BramChen, @mwfogleman, @nameanyone, @natecain, @pekopeko1, @pmario, @sukima, @xcazin.
See GitHub for detailed change history of this release
This is an emergency release that fixes a single significant bug with shadow tiddler handling in 5.0.11. See the discussion thread for more details.
See GitHub for detailed change history of this release
This release includes a number of features designed to improve the experience of TiddlyWiki with a screen reader. Particular thanks to @domasofan for his feedback
text/html tiddlers so that they are displayed within an HTML iframe element@Jermolene would like to thank the contributors to this release who have generously given their time to help improve TiddlyWiki:
See GitHub for detailed change history of this release
*.hta{{!!tags}})$:/tags/PageControls)See GitHub for detailed change history of this release
This release includes minor bug fixes and documentation updates.
See GitHub for detailed change history of this release
tiddlywiki.info file in the root of wiki folder file is now optional, falling back to a default configuration suitable for serverside use (commit)tiddlers subfolder in the wiki folderThis release includes minor bug fixes and documentation updates.
See GitHub for detailed change history of this release
See GitHub for detailed change history of this release
See GitHub for detailed change history of this release
These are changes that might affect users upgrading from previous betas.
See GitHub for detailed change history of this release
See Notes for upgrading to 5.0.8-beta for more details of these changes:
.multids MultiTiddlerFilesSee GitHub for detailed change history of this release
$:/ prefixlist-before and list-after fields for controlling tag ordering (see TiddlerTags for details)sourceURL handling to eval() so that tiddler modules can be properly debugged in Chrometw-site-title for the site titleHere are the details of recent releases of TiddlyWiki5. See TiddlyWiki5 Versioning for details of how releases are named.
See GitHub for detailed change history of this release
This release includes a number of features designed to improve the experience of TiddlyWiki with a screen reader. Particular thanks to @domasofan for his feedback
text/html tiddlers so that they are displayed within an HTML iframe element@Jermolene would like to thank the contributors to this release who have generously given their time to help improve TiddlyWiki:
See GitHub for detailed change history of this release
This is an emergency release that fixes a single significant bug with shadow tiddler handling in 5.0.11. See the discussion thread for more details.
See GitHub for detailed change history of this release
See Notes for upgrading to 5.0.11-beta for more details of these changes:
/output folder within TiddlyWikiFolders (it used to be current directory)[link text](#TiddlerTitle)[ext[tooltip|url]]).tid TiddlerFiles to allow single line text fields$:/ShowEditPreview to $:/state/showeditpreviewI (@Jermolene) would like to thank the contributors to this release who have generously given their time to helping improve TiddlyWiki:
@BramChen, @mwfogleman, @nameanyone, @natecain, @pekopeko1, @pmario, @sukima, @xcazin.
See GitHub for detailed change history of this release
[is[tag]] to the FilterOperator: is[untagged[]] filter operatorSee GitHub for detailed change history of this release
$:/ prefixlist-before and list-after fields for controlling tag ordering (see TiddlerTags for details)sourceURL handling to eval() so that tiddler modules can be properly debugged in Chrometw-site-title for the site titleSee GitHub for detailed change history of this release
See Notes for upgrading to 5.0.8-beta for more details of these changes:
.multids MultiTiddlerFilesSee GitHub for detailed change history of this release
These are changes that might affect users upgrading from previous betas.
See GitHub for detailed change history of this release
See GitHub for detailed change history of this release
See GitHub for detailed change history of this release
tiddlywiki.info file in the root of wiki folder file is now optional, falling back to a default configuration suitable for serverside use (commit)tiddlers subfolder in the wiki folderThis release includes minor bug fixes and documentation updates.
See GitHub for detailed change history of this release
This release includes minor bug fixes and documentation updates.
See GitHub for detailed change history of this release
*.hta{{!!tags}})$:/tags/PageControls)See GitHub for detailed change history of this release
$:/theme isn't defined or refers to a missing tiddler, then fallback through Snow White to Vanilla. This means that empty.html now defaults to Snow White$:/tags/PageControls tiddlers from being reordered5.0.x-beta and the final release will be 5.1.xSee GitHub for detailed change history of this release
See GitHub for detailed change history of this release
$:/state/tab/sidebar-{$:/core/ui/SideBar|$:/core/ui/SideBar||}{$:/core/ui/PageTemplate|$:/core/ui/PageTemplate||} one gets $:/state/tab/sidebar-{1743827719}$:/tags/PageTemplate$:/core/templates/tiddlywiki5.template.html to $:/core/save/allContributors to this release include @jermolene, @asampal and @pmario.
See GitHub for detailed change history of this release
tw-close-other-tiddlers message (eg, )<$setvariable> to <$set><$setvariable> will temporarily remain as a synonym for <$set> for the next few releasesfields and index attributes of the TranscludeWidgetContributors to this release include @jermolene and @grayeul.
See GitHub for detailed change history of this release
This release has several bug fixes:
See GitHub for detailed change history of this release
This release has several bug fixes:
<$edit-text> widget<<tabs>> macro to the tiddler info panel, the control panel and the sidebarcaption field for the text of the tab:list field of the corresponding tag tiddlerSee GitHub for detailed change history of this release
This minor release just contains fixes for the syncer and related adaptor modules for the TiddlyWeb edition and for TiddlyWiki5's integrated server.
This release is the culmination of a large scale refactoring of the widget mechanism of TiddlyWiki5. There are several changes to be aware of if upgrading from earlier versions:
<$setstyle> - use <div style=<<macroName Param>>> instead<$video> - will return in a later release<$datauri> - use the <<makedatauri>> built-in macro instead<$error> - may return in a later release<$import> - use the BrowseWidget, DropzoneWidget and NavigatorWidget instead<$info> - use the <<changecount>> built-in macro instead<$version> - use the <<version>> built-in macro instead<div> or a <span> to be able to style the content<$view format="link"/> is no longer available; use an explicit <$link> widget instead<$view format="link"/> is no longer available; use the TranscludeWidget insteadtiddler is used to reference a tiddler by title, not titlebody element now has the class tw-body, which will need to be specified in any overrides<body> elements in a documentpackage.json to the new version numberbld.sh to build the deployment filespackage.json to the previous version numberverbump "5.0.8-beta", substituting the new version numberdeploy.shwbld.sh <username> <password>Render an individual tiddler as a specified ContentType, defaults to text/html and save it to the specified filename:
--rendertiddler <title> <filename> [<type>]By default, the filename is resolved relative to the output subdirectory of the edition directory. The --output command can be used to direct output to a different directory.
Any missing directories in the path to the filename are automatically created.
Render a set of tiddlers matching a filter to separate files of a specified ContentType (defaults to text/html) and extension (defaults to .html).
--rendertiddlers <filter> <template> <pathname> [<type>] [<extension>]For example:
--rendertiddlers [!is[system]] $:/core/templates/static.tiddler.html ./static text/plainBy default, the pathname is resolved relative to the output subdirectory of the edition directory. The --output command can be used to direct output to a different directory.
Any files in the target directory are deleted. The target directory is recursively created if it is missing.
There are two ways to report bugs in TiddlyWiki:
Unless you are already familiar with GitHub, it's usually easiest to report problems through the discussion groups.
We use GitHub Issues to manage bug reports and feature requests for TiddlyWiki. To maintain their effectiveness we endeavour to have as few open issues as possible.
Open issues should be actionable: generally either a reproducible bug report, or a specific feature request. From the perspective of the core developers, the issues list behaves like a shared todo list. Every item on the list requires a little bit of attention each time we check the list.
GitHub Issues are not very good for managing ideas that are not immediately actionable. Better to use the TiddlyWiki discussion groups for open ended questions, or speculative discussions of new features.
Before creating a GitHub issue it is good etiquette to search through the existing issues to see whether the problem has already been reported. If a search isn't practical, don't worry too much; GitHub makes it easy to merge existing issues.
When you do create an issue, remember that for effective debugging, we need as much information as possible. At a minimum, please try to include:
Consider also adding screenshots if it makes things clearer.
There's a lot of good material on the web about bug reports:
These resources created by the TiddlyWiki Community help you get the best out of TiddlyWiki. Submit new entries via GitHub, Twitter or by posting in the TiddlyWiki Groups.
Matabele's stylish and clean system for personal task management.
This is my work in progress version of TW5, incorporating various features and ideas as and when they intrigue me. To grab any feature you may wish to try, drag the listed tiddlers across to the dropzone of an empty TiddlyWiki 5.0.10-beta
A collection of TiddlyWiki resources from Mario Pietsch, with a focus on cloud deployments. Mario also maintains the German translation of TiddlyWiki.
My name is Mario Pietsch from Austria. I'm living near Salzburg.
This page, will be the portal to my TiddlyWiki, TiddlyWeb related content.
An experimental MathJax plugin for TiddlyWiki version 5. As Martin says, the implementation is a bit of a hack but may be useful until we have a better alternative.
Welcome. I have created plugin for TiddlyWiki 5 which allows you to use MathJax (math in TeX and MathML) inside TiddlyWiki 5. It's unofficial plugin and it doesn't follow general policy of TiddlyWiki as stand-alone solution but it works. So you can use it if you want.
Notes and tips by a developer working on writing TiddlyWiki plugins – including TWExe, a widget for running Windows scripts and executables.
A translation of the tiddlywiki.com documentation from Bram Chen, TiddlyWiki's Chinese translator.
Huge collection of customisations and tweaks from Ton Gerner.
I am a longtime user of TiddlyWiki Classic and still use it daily since you can't do everything in TiddlyWiki 5 (yet) ;)
I started experimenting with TW5 at the end of September 2013 (alpha10). Since I missed a few things in the layout I got used to in TiddlyWiki Classic 1, I started with modifying the layout of TW5. To share my knowledge, I made a few guides about these 'modifications'. The guides started as a non-linear personal web notebook (yeah, the subtitle of TiddlyWiki!). I started experimenting with layout things and used TW5 to document my experiments.
buggyj has created several useful plugins, including a WYSIWYG HTML editor, a configurable calendar and tag lists with draggable ordering.
A collection of customisations and macros from Danielo Rodriguez.
This is my personal tiddlywiki file for testing.
Here I will post the tools and Macros that I develop for this awesome tool. That way, all the help the comunity gave me can came back to the comunity again.
Stephan Hradek's growing catalogue of tips and tutorials. Stephan has also developed several plugins and macros that you can find at http://tiddlystuff.tiddlyspot.com/.
Some things in TiddlyWiki seem like Magic. As my preferred nick is Skeeve, I felt that TW5 Magick is a proper name for this collection of some of the "magic" tricks one can do with TiddlyWiki.
Chris Hunt's detailed developer tutorials for getting started with writing widgets for TiddlyWiki.
These pages document aspects TiddlyWiki5 programming, sharing "lessons learned" to help developers to get started with TiddlyWiki5 customization and extension.
There are currently two articles in this wiki:
- A Simple Widget
- A More Complex Widget
Dave Gifford's growing catalogue of tips and tutorials.
TiddlyWiki 5 is a great tool for note-taking, bookmarking, blogging, organizing to do lists, writing books, and more. But many of the things that can be done in TiddlyWiki 5 are often hidden to the new user, either because the user doesn't know about it or because the user doesn't know how to do it. TW5 mall is a modest catalog of hacks where you can discover new tricks in TiddlyWiki 5 and also find out in layman's terms how to implement them.
A beautifully presented timeline widget using vis.js (http://visjs.org).
Source: https://github.com/emkayonline/tw5visjs
This plug-in allows TW5 to display tiddlers using the vis.js graphical timeline and graph widgets.
This plug-in has been testing on OS X with Safari, Chrome and Firefox, but should work under all operating systems and browser supported by TW5 and vis.js.
Also, the plug-in has been designed to work off-line, enabling it to be used without a wireless connection on an iPad/iPhone using TWEdit
Tips and guides for using TiddlyWiki.
I never used Node.js until a couple weeks ago when I wanted to try a TW5 installation on Node and expand my knowledge a bit. I figured someone else may be in the same boat so I wrote it all down
A collection of articles covering integration with Fargo, Font Awesome and Google Calendar, and tips for managing task lists.
I have become a regular user of TiddlyWiki and have become so accustomed to using Font Awesome icons in Fargo that I wanted to incorporate the icons into my wikis as well.
The reveal widget hides or shows its content depending upon the value of a state tiddler. The type of the widget determines the condition for the content being displayed:
The content of the <$reveal> widget is displayed according to the rules given above.
| Attribute | Description |
|---|---|
| state | The title of the tiddler containing the state |
| type | The type of matching performed: match, nomatch or popup |
| text | The text to match when the type is match and nomatch |
| position | The position used for the popup when the type is popup. Can be left, above, aboveright, right, belowleft or below |
| default | Default value to use when the state tiddler |
| animate | Set to "yes" to animate opening and closure (defaults to "no") |
| retain | Set to "yes" to force the content to be retained even when hidden (defaults to "no") |
Retaining the content when hidden can give poor performance since the hidden content requires refresh processing even though it is not displayed. On the other hand, the content can be revealed much more quickly. Note that setting animate="yes" will also force retain="yes".
Here's a simple example of showing and hiding content with buttons:
A slider appears as a single button that can be used to toggle the display of the contained content.
Here is a simple example of a popup built with the RevealWidget:
TiddlyWiki is under rapid development at the moment as it moves through beta to a full release.
During the beta TiddlyWiki will be practical for cautious everyday use but as we perfect the product there will occasionally be situations where we have to make changes that are not backwards compatible. These occasions will be clearly marked in the release notes.
The following additional features are planned or under consideration for implementation during the beta:
[img[url]] for remote image embedding, and [ext[url]] for explicit external linksAlso see the issues list on GitHub: https://github.com/Jermolene/TiddlyWiki5
TiddlyWiki will leave beta and become a full release in the summer of 2014. That is the point at which it is declared stable enough for general use. It will continue to improve and evolve after this point, although constrained to remain backwards compatible so that plugins and content created for version 5.0 will continue to work into the indefinite future.
Safe mode provides a way to disabling most customisations in TiddlyWiki. This is useful because if TiddlyWiki is customised incorrectly it can be rendered inoperable. A particular issue is that some customisations break when upgrading to a newer core version of TiddlyWiki (especially during the beta).
Safe mode is enabled in the browser by starting TiddlyWiki with the URL hash set to the string #:safe. For example:
In safe mode, any tiddlers that override shadow tiddlers are renamed to give them the prefix SAFE: , thus restoring the underlying shadow tiddler.
A report tiddler is displayed that allows you to inspect the tiddlers that were renamed.
This is a demonstration alert.
Note that the trashcan icon deletes the tiddler containing this alert. You can also remove it by opening the tiddler SampleAlert and editing it to remove the tag $:/tags/Alert.
Saves an individual tiddler in its raw text or binary format to the specified filename.
--savetiddler <title> <filename>By default, the filename is resolved relative to the output subdirectory of the edition directory. The --output command can be used to direct output to a different directory.
Any missing directories in the path to the filename are automatically created.
Saves a group of tiddlers in their raw text or binary format to the specified directory.
--savetiddlers <filter> <pathname>By default, the pathname is resolved relative to the output subdirectory of the edition directory. The --output command can be used to direct output to a different directory.
Any missing directories in the pathname are automatically created.
The built-in TiddlySpot saver can also be used to save changes to a simple PHP script that you can run on most hosting providers.
These are preliminary instructions that need verification
$USERS = array( 'UserName1'=>'Password1', etc) and replace Username1 and Password1 with your desired username and passwordThe control panel Saving tab includes the following configuration options:
| Name | Description |
|---|---|
| Server URL | The full URL to the store.php file on your server |
| Upload filename | The filename used to save the TiddlyWiki (defaults to index.html) |
| Upload directory | The relative path from store.php to the directory used for saving the file |
| Backup directory | The relative path from store.php to the directory used for backups |
The AndTidWiki app for Android devices makes it possible to edit and save changes to TiddlyWiki5, including working offline without a network connection.
Note that AndTidWiki is published independently of TiddlyWiki
By default, TiddlyWiki saves changes on InternetExplorer 10 and above using a saver module that downloads the newly modified file, rather than saving it directly. There are two alternatives that both save changes directly to the file:
*.hta.The iPad/iPhone app TWEdit makes it possible to edit and save changes to TiddlyWiki5, including working offline without a network connection. Download it here.
Instructions for use:
http://tiddlywiki.com/empty.html.html)Note that TWEdit is published independently of TiddlyWiki
TiddlySpot is a free hosting service for TiddlyWiki documents from Simon and Daniel Baird. It has been in operation almost as long as TiddlyWiki itself.
TiddlyWiki5 isn't yet built in to TiddlySpot but you can use it by following these steps:
When used as a single HTML file, TiddlyWiki5 allows content to be encrypted using the Stanford JavaScript Crypto Library.
This method of saving changes is clunky but has the advantage of working on almost all desktop browsers, and many mobile browsers.
If the button doesn't work save this link: http://tiddlywiki.com/empty.html
Your browser may ask you to accept the download before it begins
.html or .htm extensionTip: most browsers have an option to prompt each time for the download location. This allows you to select the existing version of the file and replace it.
If you're using Firefox for Android, see the instructions for Saving with TiddlyFox on Android.
.html or .htm extension(Alternatively, see the video tutorial)
(to save the link, ensure you've installed the "save-link-menus" extension and then long-press on the link and choose "Save link")
You may also see a prompt to enable the Microsoft Script Runtime
Your browser may ask you to accept the download before it begins
.html extensionYou might expect that TiddlyWiki's architecture as a SinglePageApplication would make it unsuitable for large amounts of data. In fact, TiddlyWiki users regularly work with files that are 20 or 30 megabytes without problems - and successful experiments have been done up into the gigabytes.
The TiddlyWiki5 repo contains several scripts that are used to build and deploy TiddlyWiki5 (.sh for *nix and .cmd for Windows). They can serve as a useful starting point for your own scripts.
bld: builds tw5.comThis script builds several variants of TiddlyWiki5 for deployment on tiddlywiki.com.
By default, files are output to a folder called jermolene.github.com, sibling to the TiddlyWiki5 repo directory. For example:
/TiddlyWork/ - Directory for working with TiddlyWiki5
|
+--+-- /TiddlyWiki5/ - Directory containing the TiddlyWiki5 repo from GitHub
|
+-- /jermolene.github.com/ - Directory for output filesYou can override the build output directory by defining the environment variable TW5_BUILD_OUTPUT. The easiest way to do this is to create a personal batch file to invoke TiddlyWiki5 that first sets the environment variable and then invokes bld.
The files output by bld are:
readme.md main readme file, output to the TiddlyWiki5 directoryindex.html TiddlyWiki5 standalone HTML file with content from the tw5.com editionempty.html TiddlyWiki5 standalone HTML file with no contentencrypted.html TiddlyWiki5 standalone HTML file encrypted with the password passwordtest.html TiddlyWiki5 browser-based test suite (see TestingMechanism)static.html static HTML version of the DefaultTiddlers of the tw5.com editionstatic/*.html and static/static.css static HTML versions of individual tiddlersbld also runs the TiddlyWiki5 Node.js-based test suite (see TestingMechanism)
serve: serves tw5.comserve.sh <username> [<password>]Or:
serve.cmd <username> [<password>]This script starts TiddlyWiki5 running as an HTTP server with the content from the clientserver edition. By default, the Node.js serves on port 8080. If the optional username parameter is provided, it is used for signing edits. If the password is provided then HTTP basic authentication is used.
To experiment with this configuration, run the script and then visit http://127.0.0.1:8080 in a browser.
Changes made in the browser propagate to the server over HTTP (use the browser developer console to see these requests). The server then syncs changes to the file system (and logs each change to the screen).
lazy: serves tw5.com with lazily loaded imageslazy.sh <username> [<password>]Or:
lazy.cmd <username> [<password>]This script serves the clientserver edition content with LazyLoading applied to images.
wbld: builds TiddlyWiki for TiddlyWebThis script builds and deploys the code for TiddlyWiki in the Sky for TiddlyWeb. If you want to experiment with your own builds of TiddlyWiki5 for TiddlyWeb you could use this batch file as a base.
2bld: builds TiddlyWiki 2.6.5This script builds TiddlyWiki 2.6.5 from the original source and then displays the differences between them (diff is used for *nix, fc for Windows).
The scrollable widget wraps its content in a scrollable frame. The user can scroll the contents with the mouse or with touch gestures. Code can use the WidgetMessage: tw-scroll to programmatically scroll specific DOM nodes into view.
The content of the <$scrollable> widget is displayed within a pair of wrapper DIVs. If the inner DIV is larger then it scrolls within the outer one. CSS is used to specify the size of the outer wrapper.
| Attribute | Description |
|---|---|
| class | The CSS class(es) to be applied to the outer DIV |
| fallthrough | See below |
If a scrollable widget can't handle the tw-scroll message because the inner DIV fits within the outer DIV, then by default the message falls through to the parent widget. Setting the fallthrough attribute to no prevents this behaviour.
This example requires the following CSS definitions from $:/_tw5.com-styles:
.tw-scrollable-demo {
border: 1px solid <<colour message-border>>;
background-color: <<colour message-background>>;
padding: 1em;
height: 400px;
}This wiki text shows how to display a list within the scrollable widget:
TiddlyWiki supports simple text searches through the search box in the sidebar. More sophisticated search options are featured in the advanced search.
All of them boil down to the use of TiddlerFilters to display the tiddlers that satisfy some criteria.
The select widget displays an HTML select element containing a list of items defined by <option> and <optgroup> elements and binds the selected value to the text of a tiddler field or index.
For example, this select widget displays a list of the tags in this wiki:
The state tiddler currently contains . See the text change as you switch entries in the select widget. Try changing the value of the state tiddler and see the select widget change. Notice how the select widget only displays an entry if there is a precise match with the tiddler text.
The content of the <$select> widget should be one or more HTML <option> or <optiongroup> elements that provide the available values.
| Attribute | Description |
|---|---|
| tiddler | The title of the tiddler containing the value (defaults to the current tiddler) |
| field | The field name for the value in the current tiddler (defaults to "text") |
| index | The index of a property in a DataTiddler (takes precedence over the field attribute) |
| class | CSS classes to be assigned to the HTML select element |
| default | Default value to be used if the tiddler, field or index specifies a missing value |
This example sets the title of the current wiki $:/SiteTitle to one of a list of book titles:
In this example the value attribute has been used to specify the text that should be used as the value of the entry instead of the display text.
Entries in the list can be grouped together with the <optgroup> element
The ListWidget can be used to generate the options for a select widget. For example, here we combine a select widget listing all the tiddlers tagged introduction with a transclusion to display the text of the selected one.
This example uses a nested pair of list widgets. The outer one generates the <optgroup> elements, and the inner one generates <option> elements:
The server built in to TiddlyWiki5 is very simple. Although compatible with TiddlyWeb it doesn't support many of the features needed for robust Internet-facing usage.
At the root, it serves a rendering of a specified tiddler. Away from the root, it serves individual tiddlers encoded in JSON, and supports the basic HTTP operations for GET, PUT and DELETE.
--server <port> <roottiddler> <rendertype> <servetype> <username> <password> <host> <pathprefix>The parameters are:
If the password parameter is specified then the browser will prompt the user for the username and password. Note that the password is transmitted in plain text so this implementation isn't suitable for general use.
For example:
--server 8080 $:/core/save/all text/plain text/html MyUserName passw0rdTo run multiple TiddlyWiki servers at the same time you'll need to put each one on a different port.
Note that this command is experimental and may change or be replaced during the TiddlyWiki version 5 beta
Sets the specified field of a group of tiddlers to the result of wikifying a template tiddler with the currentTiddler variable set to the tiddler.
--setfield <filter> <fieldname> <templatetitle> <rendertype>The parameters are:
"favicons" are small icons that most browsers display to help users identify websites.
When TiddlyWiki starts up in the browser it looks for a tiddler called $:/favicon.ico and dynamically uses it as the favicon for the page. If you modify the image then the favicon changes instantly to reflect it.
On the server, the ServerCommand will serve the tiddler $:/favicon.ico at the path /favicon.ico.
The <$setvariable> widget has been renamed <$set/>; see SetWidget for more details.
For the moment, you can continue to use <$setvariable> as a synonym for <$set/>, but it will be removed for the beta.
The set variable widget assigns a value to a specified variable. The new value of the variable is availale to the content within the set variable widget.
The content of the <$set> widget is the scope for the value assigned to the variable.
| Attribute | Description |
|---|---|
| name | The name of the variable to assign |
| value | The value to assign to the variable |
ShadowTiddlers are tiddlers that are loaded from within Plugins. Unlike ordinary tiddlers, they don't appear in most lists.
ShadowTiddlers can be overridden with an ordinary tiddler of the same name. If that tiddler is subsequently deleted then the original shadow tiddler is automatically restored.
The current shadow tiddlers are:
You can work on a TiddlyWiki file in Dropbox and publish a URL that anyone can use to see a read-only view of the file.
https://www.dropbox.com/s/<gobbledegook>/mywiki.html
https://dl.dropboxusercontent.com/s/<gobbledegook>/mywiki.html
The result is a "secret" URL that you can send to other people to enable them to see the wiki.
A single file application is a web application where all of the assets are delivered in a single static file. This means that it can be downloaded and used offline without losing functionality. It can also be hosted on almost any type of web server.
TiddlyWiki is an unusual single file application because it stores its data within the same file, and is capable of saving changes to itself.
Every single file application must also by definition be a SinglePageApplication, but the converse is not true.
As defined by Wikipedia, a SinglePageApplication is a web application that presents itself as a single HTML document that dynamically loads additional content as the user browses the site. Frequently, single page applications are carefully designed to hide their nature, appearing and functioning as an ordinary static website by respecting the address bar and the back/forward navigation controls.
Unusually, TiddlyWiki is also a SingleFileApplication.
The startup mechanism runs the installed startup modules at the end of the boot process.
Modules with their module-type field set to startup:
startup functionstartup(), asynchronous modules are passed a callback they must invoke on completion: startup(callback)name property that is used to identify the taskafter property containing an array of names of dependent tasks that must be run before this onebefore property containing an array of names of tasks that must be run after this oneplatforms property containing an array of names of platforms that are required in order for the startup module to be executed. The defined platforms are node and browser. If the platforms property is not provided it defaults to ["node","browser"]Startup modules are executed in sequence according to their declared dependencies.
There is no guarantee of the execution order of tasks that share the same dependencies.
The core defines the following startup modules:
The StateMechanism in TiddlyWiki is at the heart of how complex user interfaces can be built from WikiText.
In the browser, the TiddlyWiki display is produced by dynamically rendering the tiddler $:/core/ui/PageTemplate. Through various transclusions and other widgets it renders the entire user interface. The dynamic rendering is accomplished by a mechanism called "binding": any changes to the tiddlers in the store are dynamically reflected in the browser display.
The stack of templates that make up the TiddlyWiki display are complex but we'll focus on the line that displays the main story column:
<$list filter="[list[$:/StoryList]]" history="$:/HistoryList" template="$:/core/ui/ViewTemplate" editTemplate="$:/core/ui/EditTemplate" storyview={{$:/view}} />Breaking down the attributes applied to the list widget:
list field of the tiddler $:/StoryList. If a tiddler is added or removed from that list then it is automatically reflected in the displayed listThe $:/StoryList tiddler is an example of a StateTiddler: a tiddler that is used to hold the state of the user interface. Changes to the user interface are made indirectly, by changing the underlying state tiddlers, and letting TiddlyWiki ripple the changes through the user interface.
Note how this approach makes the open tab in the sidebar very easy to implement: it is just another list widget referencing the same state tiddler, but with a different template:
<$list filter="[list[$:/StoryList]]" history="$:/HistoryList" storyview="pop">
<$button message="tw-close-tiddler" class="btn-invisible btn-mini">×</$button> <$link to={{!!title}}><$view field="title"/></$link>
</$list>Now consider the implementation of the info panel within the tiddler template. We want to be able to toggle the info panel open and closed, which means that we must track its current state in a tiddler.
However, we can't track the state in a tiddler called, say, $:/InfoPanelState because every tiddler would share the same state; changing the value of the tiddler would affect all tiddlers displayed in the story.
The solution is to dynamically generate a unique title for each state tiddler that we need. We need to ensure that the same state tiddler title is generated each time a user interface element is rendered. To do that, we append together tokens representating each of the stack of transclusions that led to the current rendering location. Then that string of symbols is hashed to a simple numeric value.
The process of generating a state tiddler title is encapsulated in the QualifyMacro.
TiddlyWiki5 provides several features to help you structure information as tiddlers, and model the relationships between them:
You can use this construction to cause the wrapped content to be assigned specified CSS classes or styles:
Similar syntax is used to assign styles. For example:
Multiple styles and classes can be mixed. For example:
SyncAdaptorModules encapsulate storage mechanisms that can be used by the SyncMechanism. Two examples are:
fs moduleSyncAdaptorModules are represented as JavaScript tiddlers with the field module-type set to syncadaptor.
The following properties should be exposed via the exports object:
| Property | Description |
|---|---|
| adaptorClass | The JavaScript class for the adaptor |
Nothing should be exported if the adaptor detects that it isn't capable of operating successfully (eg, because it only runs on either the browser or the server, or because a dependency is missing).
Adaptor modules must handle the following methods.
Constructor(syncer)Initialises a new adaptor instance.
| Parameter | Description |
|---|---|
| syncer | Syncer object that is using this adaptor |
getTiddlerInfo(tiddler)Gets the supplemental information that the adaptor needs to keep track of for a particular tiddler. For example, the TiddlyWeb adaptor includes a bag field indicating the original bag of the tiddler.
| Parameter | Description |
|---|---|
| tiddler | Target tiddler |
Returns an object storing any additional information required by the adaptor.
getStatus(callback)Retrieves status information from the server. This method is optional.
| Parameter | Description |
|---|---|
| callback | Callback function invoked with parameters err,isLoggedIn,username |
login(username,password,callback)Attempts to login to the server with specified credentials. This method is optional.
| Parameter | Description |
|---|---|
| username | Username |
| password | Password |
| callback | Callback function invoked with parameter err |
logout(callback)Attempts to logout of the server. This method is optional.
| Parameter | Description |
|---|---|
| callback | Callback function invoked with parameter err |
getSkinnyTiddlers(callback)Retrieves a list of skinny tiddlers from the server.
This method is optional. If an adaptor doesn't implement it then synchronisation will be unidirectional from the TiddlyWiki store to the adaptor, but not the other way.
| Parameter | Description |
|---|---|
| callback | Callback function invoked with parameter err,tiddlers, where tiddlers is an array of tiddler field objects |
saveTiddler(tiddler,callback)Saves a tiddler to the server.
| Parameter | Description |
|---|---|
| tiddler | Tiddler to be saved |
| callback | Callback function invoked with parameter err,adaptorInfo,revision |
loadTiddler(title,callback)Loads a tiddler from the server.
| Parameter | Description |
|---|---|
| title | Title of tiddler to be retrieved |
| callback | Callback function invoked with parameter err,tiddlerFields |
deleteTiddler(title,callback)Delete a tiddler from the server.
| Parameter | Description |
|---|---|
| title | Title of tiddler to be deleted |
| callback | Callback function invoked with parameter err |
System tags are used to give special behaviour to tiddlers:
These are the system tags in use in this wiki:
System tiddlers are any tiddler whose title starts with $:/; such tiddlers are automatically hidden from most operations. They don't show up in lists or search results, but linking to one directly works in the usual way.
TiddlyWiki models everything as tiddlers, including its internal components and configuration. Thus, even an apparently empty TiddlyWiki actually contains dozens of tiddlers that are necessary to enable it function correctly. Using system tiddlers prevents them from confusing casual users.
The current system tiddlers are:
TiddlyWiki5 formats tables using vertical bar characters like so:
|!Cell1 |!Cell2 |
|Cell3 |Cell3 |Exclamation marks are used to indicate header cells. The example renders as:
| Cell1 | Cell2 |
|---|---|
| Cell3 | Cell3 |
Table cell alignment is controlled by inserting space characters before and/or after the cell content. For example:
|Left aligned content |
| Right aligned content|
| Centred content |
|+++ a very wide column so we can see the alignment +++|The example renders as:
| Left aligned content |
| Right aligned content |
| Centred content |
| +++ a very wide column so we can see the alignment +++ |
Vertical alignment of cells is done by inserting either a ^ for top alignment or a , for bottom alignment as the first character of a cell. The normal horizontal alignment is still possible. For example:
|^top left |^ top center |^ top right|
|middle left | middle center | middle right|
|,bottom left |, bottom center |, bottom right|The example renders as:
| :: | ::::::::::::::::::::::::::: | ::::::::::::::::::::::::::: | ::::::::::::::::::::::::::: | :: |
| :: :: | top left | top center | top right | :: :: |
| :: :: | middle left | middle center | middle right | :: :: |
| :: :: | bottom left | bottom center | bottom right | :: :: |
| :: | ::::::::::::::::::::::::::: | ::::::::::::::::::::::::::: | ::::::::::::::::::::::::::: | :: |
If you need to have a ^or a , as the first character of a left aligned cell, you can use HTML escaping:
^ | ^ |
, | , |
To merge a table cell with the one above, use the special cell text ~. To merge a cell with the one to its left use the text <. To merge one to its right use >. For example:
|Cell1 |Cell2 |Cell3 |Cell4 |
|Cell5 |Cell6 |Cell7 |<|
|Cell5 |~|Cell7 |Cell8 |
|>|Cell9 |Cell10 |Cell11 |Renders as:
| Cell1 | Cell2 | Cell3 | Cell4 |
| Cell5 | Cell6 | Cell7 | |
| Cell5 | Cell7 | Cell8 | |
| Cell9 | Cell10 | Cell11 | |
Table CSS classes, captions, headers and footers can be specified as special pseudo-rows:
|myclass anotherClass|k
|This is a caption |c
|Cell1 |Cell2 |
|Cell3 |Cell3 |
|Header|Header|h
|Footer|Footer|fRenders as:
| Cell1 | Cell2 |
| Cell3 | Cell3 |
| Header | Header |
| Footer | Footer |
The tabs macro displays a list of tiddlers as a tab control. The user can switch between tabs by clicking on them. The tabs are labelled with the title of the corresponding tiddler, unless there is a caption field present in which case it is used instead.
By default the tab control arranges the tabs horizontally with the content underneath. You can also choose to have the tabs arranged vertically by passing the class tw-vertical.
| Position | Name | Description | Default |
|---|---|---|---|
| 1st | tabsList | Filter giving the tiddlers to be displayed | |
| 2nd | default | Name of the tiddler containing the default tab | |
| 3rd | state | String to distinguish multiple tabs within the same tiddler (use of the system tiddler prefix is recommended) | $:/state/tab |
| 4th | class | Additional CSS classes for the three wrappers DIV of the tab |
Here is an example of the tabs macro:
<<tabs "Docs WikiText Features RoadMap" "WikiText" "$:/state/tab1">>TiddlyWiki5 is a JavaScript wiki that can run entirely in the browser, or under Node.js. Internally, it is a representation transformation engine. It parses WikiText and renders it as text, or straight to the DOM with selective refresh to reflect subsequent changes. WikiText is used to render the user interface as well as the content of tiddlers. Once you know how to edit a tiddler you know how to customise TiddlyWiki, with no limits - it's only JavaScript.
Why is TiddlyWiki different? It frees you from the monopoly platforms of the web: store stuff in TW5 and you can pretty much guarantee you'll still have it in 100 years. Freedom, into the far future.
Store your tiddlers in a single HTML file along with the JS
acceptStore your tiddlers in separate files in a chain of linked directories.
./bld.sh./serve.sh UserNameBelow the line...
$tw.wiki.deleteTiddler("HelloThere")$tw.wiki.addTiddler({title: "HelloThere", text: "This is a new [[Tiddler]], linking to a TiddlerThatDoesntCurrentlyExist"})$tw.wiki.getTiddlerLinks("HelloThere")$tw.wiki.filterTiddlers("[tag[mechanism]sort[modified]]")TiddlyWiki5 can be used as a simple task management system without further customisation. The idea is that tasks be tagged task, with those that are completed also tagged done. In this way it is straightforward to generate task lists.
A template tiddler is not in fact a type of tiddler, it is a role in which a tiddler can be used.
When text is wikified there is the concept of the CurrentTiddler. Certain widgets (like the ViewWidget) can use the current tiddler implicitly. For example:
<$view tiddler="HelloThere" field="myfield"/> - displays the field "myfield" of the tiddler HelloThere
<$view field="myfield"/> - displays the field "myfield" of the current tiddlerWhen the TranscludeWidget pulls in the content from another tiddler, by default it does not change the current tiddler, so the transcluded content behaves as if it were in the context of the transcluding tiddler.
So, if we have a tiddler "A" that contains:
<$view field="myfield"/>And then transclude it from a tiddler "B" like so:
My field value is: <$transclude tiddler="A"/>The result will be that the field from the tiddler "B" is displayed; in other words, tiddler "A" is acting as a template for displaying information from tiddler "B".
The TiddlerWidget is used to change the current tiddler. Consider a tiddler "C" containing:
<$tiddler tiddler="A"><$transclude tiddler="A"/></$tiddler>It is still transcluding tiddler "A", but now it is also setting the current tiddler to "A". The result is therefore that the field "myfield" for tiddler "A" is displayed.
The shorthand syntax for Transclusion in WikiText actually generates both a TiddlerWidget and a TranscludeWidget.
TiddlyWiki5 incorporates the Jasmine JavaScript testing framework (see http://pivotal.github.io/jasmine/). It allows the same tests to be run both in the browser and under Node.js.
There are two main elements to the TiddlyWiki5 testing mechanism:
tiddlywiki/jasmine that wraps Jasmine up into a plugin along with some glue codetest that contains the core test specifications and includes the Jasmine pluginTo run the tests under Node.js just load up the test wiki:
node ./tiddlywiki.js \
./editions/test \To generate a wiki containing the browser tests load up the test wiki and save it as an HTML file:
node ./tiddlywiki.js \
./editions/test \
--verbose \
--rendertiddler $:/core/save/all $TW5_BUILD_OUTPUT/test.html text/plain \Then, open the test.html file in the browser to see the test results. There is a prebuilt version of test.html at:
A TextReference identifies a chunk of text from a tiddler that can be retrieved or modified depending on the context.
Text references are made up of several parts, most of which can be optional:
<tiddler title> - the text field of the specified tiddler<tiddler title>!!<metadata field> - a tiddler metadata field (eg, modified, modifier, type etc)!!<metadata field> - a metadata field of the current tiddler<tiddler title>##<property index> - extracts a named property from DataTiddlersText references can be used in several places:
<$list filter="[tag{MyTag!!name}]"/>)<$widget attrib={{Title!!description}}/>){{MyTiddler!!title}})state attribute of the RevealWidget and the LinkCatcherWidgetThe text widget displays plain text.
The content of the <$text> widget is not used.
| Attribute | Description |
|---|---|
| text | The text to display |
Every so often, TiddlyWiki users report heart-rending tales of personal data loss on the discussion groups:
My entire TiddlyWiki has just been wiped out when Firefox crashed during saving a tiddly.
https://groups.google.com/d/topic/tiddlywiki/oG2L7OXhUoI/discussion
Last time I used it was last night at home on my Windows 7 desktop, hit the check mark to stop editing my last entry, it then saves via TiddlyFox and I eject my USB drive. I came to work this morning, plugged in my USB, enter my TW5 password and it doesn't want to open after several attempts. I browse to my TW5 html file and notice that my file size is no longer 3MB.. instead it is 80KB. This leads me to believe I lost everything.
https://groups.google.com/d/topic/tiddlywiki/SXStDJ0ntGI/discussion
Don't let it happen to you!
Backup your data!
TiddlyWiki is a very flexible, customisable system that puts you firmly in charge of your own data. Every care is taken in TiddlyWiki's development to ensure that it is a safe place to preserve your most valuable data but the ultimate responsibility to reduce the risk of data loss falls to users.
The best way to make sure that your data is safe is to practice a rigorous system of backups:
TiddlerFields are name:value pairs that make up a tiddler. Field names must be lowercase letters, digits or the characters - (dash), _ (underscore) and . (period).
The standard fields are:
| Field Name | Reference | Description |
|---|---|---|
title | TitleField | |
text | TextField | |
modified | ModifiedField | |
modifier | ModifierField | |
created | CreatedField | |
creator | CreatorField | |
tags | TagsField | |
type | TypeField | |
list | ListField |
Other fields used by the core are:
| Field Name | Reference | Description |
|---|---|---|
color | ColorField | |
description | DescriptionField | |
draft.of | DraftOfField | |
draft.title | DraftTitleField | |
footer | FooterField | |
library | LibraryField | |
name | NameField | |
plugin-priority | PluginPriorityField | |
plugin-type | PluginTypeField | |
source | SourceField | |
subtitle | SubtitleField |
The TiddlyWebAdaptor uses a few more fields:
| Field Name | Reference | Description |
|---|---|---|
bag | BagField | |
revision | RevisionField |
See the Advanced > TiddlerFields tab of the control panel for details of the fields used in this wiki.
Tiddlers can be stored in text files in several different formats. Files containing single tiddlers can also have an auxiliary .meta file formatted as a sequence of name:value pairs:
title: TheTitle
modifier: someoneThese files consist of a sequence of lines containing name:value pairs, a blank line and then the text of the tiddler. For example:
title: MyTiddler
modifier: Jeremy
This is the text of my tiddler.Note that many text editors require that files include a terminating newline. If you want to avoid including the terminating newline in the text of the tiddler you can use this alternative syntax:
title: MyTiddler
modifier: Jeremy
text: This is the text of my tiddler.The ContentType application/x-tiddler is used internally for these files
<DIV> .tiddler filesModern *.tiddler files look like this:
<div title="AnotherExampleStyleSheet" modifier="blaine" created="201102111106" modified="201102111310" tags="examples" creator="psd">
<pre>Note that there is an embedded <pre> tag, and line feeds are not escaped.
And, weirdly, there is no HTML encoding of the body.</pre>
</div>These *.tiddler files are therefore not quite the same as the tiddlers found inside a TiddlyWiki HTML file, where the body is HTML encoded in the expected way.
Older *.tiddler files more closely matched the store format used by TiddlyWiki at the time:
<div tiddler="AnotherExampleStyleSheet" modifier="JeremyRuston" modified="200508181432" created="200508181432" tags="examples">This is an old-school .tiddler file, without an embedded <pre> tag.\nNote how the body is "HTML encoded" and new lines are escaped to \\n</div>The ContentType application/x-tiddler-html-div is used internally for these files
These files are a straightforward array of hashmaps of name:value fields. Currently only these known fields are processed: title, text, created, creator, modified, modifier, type and tags.
The ContentType application/json is used internally for these files
TiddlyWiki HTML files contain a collection of tiddlers encoded in <DIV> format.
TiddlerFilters follow a formal grammar that is presented here for users who are familiar with the notation. It isn't necessary to understand this grammar in order to write your own filter expressions.
<filter-string> ::= <opt-whitespaces> <filter-operand> | <opt-whitespaces> <filter-operand> <filter-string>
Whitespace is matched with javascript "\s+", which matches space, tab, carriage return, new line, vertical tab, and form feed.
<opt-whitespaces> ::= <opt-whitespace> | <opt-whitespace> <opt-whitespaces>
<opt-whitespace> ::= " " | "\t" | "0xD" | "0xA" | "0xB" | "0xC"
<filter-operand> ::= <opt-operation-prefix> <string-or-operator-list>
<opt-operation-prefix> ::= "+" | "-" | ""
<string-or-operator-list> ::= <operation> | "\"" <string> "\"" | "'" <string> "'" | <string>
<operation> ::= "[" <operator-list> "]"
<operator-list> ::= <operator> | <operator> <operator-list>
<operator> ::= <opt-operator-prefix><operator><operand>
<opt-operator-prefix> ::= "!" | ""
<operator> ::= <operator-name> | <operator-name> ":" <opt-operator-suffix>
<operator-name> ::= "" | "is" | "has" | "each" | "field" ...
<opt-operator-suffix> ::= <string> | ""
<operand> ::= "[" <search-string> "]" | "{" <indirect-search-string> "}" | <regex>
<regex> ::= "/" <string> "/" <opt-regex-args>
<opt-regex-args> ::= "(" <regex-args> ")" | ""
<regex-args> ::= <regex-arg> | <regex-arg> <regex-args>
<regex-arg> ::= "m" | "y" | "g" | "i"
<string> ::= <string-type-1> | <string-type-2> | ...
At the end of parsing you end up with some or all of:
These are used differently by the different operators. For example, the field filter operator supports:
NOTES:
Note that <filter-operand>s are not commutative!
Filters are used in TiddlyWiki to choose tiddlers by specifying simple match criteria. They are used by widgets like the ListWidget and the CountWidget to perform operations on multiple tiddlers at once.
The most common filter operators are:
See FilterOperators gives a complete list of available filter operators
Links are regions of a tiddler that can be clicked to cause navigation to a different tiddler. The navigation behaviour is determined by the current StoryView; the classic TiddlyWiki view displays the story as a linear sequence of tiddlers.
Holding the control or command key while clicking on a tiddler link opens the target tiddler but doesn't navigate to it. This can be a useful way of queueing up tiddlers to be read later.
Links are useful for modelling organic relationships between tiddlers, and particularly for expressing the navigational paths between tiddlers.
The TiddlerInfoPanel lists incoming links to a tiddler in the tab References.
TiddlerFilters can include the following filter operators that work with links:
[links[]] - returns the titles of the tiddlers that are linked from the currently selected tiddler(s)[backlinks[]] - returns the titles of the tiddlers that link to the currently selected tiddler(s)TiddlyWiki5 alters the appearance of tiddler links to convey additional information about the target of the link:
| Link description | Link appearance |
|---|---|
| To a tiddler that exists | LikeThis |
| To a tiddler that doesn't exist | LikeThis |
| To a shadow tiddler that has not been overridden | LikeThis |
| To a shadow tiddler that has been overridden by an ordinary tiddler | LikeThis |
External links are shown like this: http://tiddlywiki.com/ or like this.
Tiddlers are the smallest unit of information in TiddlyWiki. Other systems have analogous concepts with more prosaic names: like "items", "entries", "entities" or "records". Even though "tiddler" is a bit of a preposterous name it has the virtue of being confusingly distinctive rather than confusingly generic.
Internally, tiddlers are an immutable dictionary of name:value pairs called fields. The only field that is required is the title field, but useful tiddlers also have a text field, and some or all of the standard fields listed in TiddlerFields.
Tiddlers can be assigned categories by assigning one or more tags. For example, tiddlers representing individuals might be tagged friend, family, colleague etc to indicate the relationship to the author.
Multiple tags can be applied to the same tiddler. Used effectively they provide a powerful way to explore content related to a tiddler.
TiddlyWiki offers several useful features based on the convention that a tag itself can be interpreted as the title of a tiddler.
Tags are displayed at the top of the tiddler as coloured pills. Clicking on a tag pill drops down a menu showing links to all the tiddlers that carry that tag, along with a link to the tiddler representing the tag itself.
When editing a tiddler, the tags pills have a small x icon that allows them to be removed individually. There is also a text box to type the name of a new tag to be added, and a dropdown autocomplete list that shows matching tags that are in use.
The tag manager is available via a button at the top of the sidebar tab "Tabs", or you can link directly to $:/TagManager.
The colour used to draw a tag pill is taken from the color field of the tiddler titled with the tag. The colour can be specified as any CSS value (more modern browsers show a colour picker for the color field).
An icon can be associated with a tag by placing the title of the tiddler containing the image into the icon field of th etiddler titled with the tag.
See the tag for an example.
The ordering used to return a list of the tiddlers with a particular tag is determined by the following rules:
See SystemTags for information about the special system tags that TiddlyWiki uses for configuration.
The TiddlerWidget sets the CurrentTiddler that applies for processing its content.
| Attribute | Description |
|---|---|
| tiddler | The title of the tiddler to become the new CurrentTiddler |
| class | CSS classes to added to the generated elements |
TiddlyDesktop is an app for working with TiddlyWiki files (both TiddlyWikiClassic and TiddlyWiki version 5). It can be installed on Windows, Mac OS X or Linux.
TiddlyDesktop is based on the OpenSource project node-webkit. The source is on GitHub:
https://github.com/Jermolene/TiddlyDesktop/
See Using TiddlyWiki on TiddlyDesktop for instructions.
TiddlyFox is an extension for Firefox that allows standalone TiddlyWiki files to save their changes directly to the file system. TiddlyFox works on both desktop and smartphone versions of Firefox. See Saving with TiddlyFox or Saving with TiddlyFox on Android for detailed instructions.
TiddlyFox can be downloaded from the Mozilla Addons site:
https://addons.mozilla.org/en-US/firefox/addon/tiddlyfox/
You can also install the latest development version of TiddlyFox direct from GitHub:
https://github.com/TiddlyWiki/TiddlyFox/raw/master/tiddlyfox.xpi
TiddlyIE is an extension for Internet Explorer that allows standalone TiddlyWiki files to save their changes directly to the file system. TiddlyIE works with the desktop version of Internet Explorer.
See Saving with TiddlyIE.
TiddlySpace is an environment for discourse on the web, built from TiddlyWeb.
TiddlySpace was originally sponsored by Osmosoft at BT.
TiddlyWeb is a server application that puts Tiddlers on the web:
TiddlyWeb can be used to host TiddlyWiki and TiddlyWiki5 wikis, making the individual tiddlers available over a flexible HTTP API.
TiddlyWeb was originally sponsored by Osmosoft at BT (along with TiddlySpace).
TiddlyWiki is a rich, interactive tool for manipulating complex data with structure that doesn't easily fit into conventional tools like spreadsheets or wordprocessors.
TiddlyWiki is designed to fit around your brain, helping you deal with the things that won't fit. The fundamental idea is that information is more useful and reusable if we cut it up into the smallest semantically meaningful chunks – tiddlers – and give them titles so that they can be structured with links, tags, lists and macros. Tiddlers use a WikiText notation that concisely represents a wide range of text formatting and hypertext features. TiddlyWiki aims to provide a fluid interface for working with tiddlers, allowing them to be aggregated and composed into longer narratives.
People love using TiddlyWiki. Because it can be used without any complicated server infrastructure, and because it is open source, it has bought unprecedented freedom to people to keep their precious information under their own control. TiddlyWiki was originally created by JeremyRuston and is now a thriving open source project with a busy Community of independent developers.
The heart of TiddlyWiki is an extensible representation transformation engine for text and images. Given the text of a tiddler and its associated ContentType, the engine can produce a rendering of the tiddler in a new ContentType. Furthermore, it can efficiently selectively update the rendering to track any changes in the tiddler or its dependents.
The processing pipeline shows how WikiText is parsed by a stack of parse rules into a parse tree. The parse tree is rendered as a tree of widgets, which is synchronised into the DOM via the RefreshMechanism.
DOM events trigger actions on widgets which update the tiddler store. The updates trigger a change event which in turn triggers the refresh mechanism to update the DOM.
TiddlyWiki is a large project with many interested parties. It benefits everyone if the code is as easy to read as possible. A key part of that it must be written and laid out consistently – the code should read as though it were written by a single author.
TiddlyWiki uses 4-character tabs for indenting.
One blank line is used to separate blocks of code. Occasional blank lines are permitted within blocks for clarity, but should be avoided unless they solve a specific readability problem.
See the following example for layout of basic JavaScript constructs:
/*
Multiline comments are used to introduce a block of code such as a function definition
*/
function demoFunction(param,more) {
// Proper sentence capitalisation for comments
if(condition == "something") {
// No space between "if" and the brackets; always spaces around binary operators
something = somethingElse;
myOtherFunction(one,two); // No whitespace within function parameters
do {
myCondition.explore(); // Always use semicolons
} while(myCondition < worsens);
}
}
Double quotes are preferred over single quotes for string literals.
TiddlyWiki is published as OpenSource which means that anyone can read the code and contribute to its development.
If you're interested in understanding more about the internal operation of TiddlyWiki, TiddlyWiki Architecture gives an overview of how TiddlyWiki is structured. Then read the code – start with the boot kernel $:/boot/boot.js.
TiddlyWiki's architecture is very different from an HTML page written using jQuery. This section concisely explains what TiddlyWiki does differently. It may not make much sense on the first reading.
The key to understanding how it works internally is to see that the RefreshMechanism requires that any region of the DOM can be regenerated at any time. This means that the entire state of the user interface must reside in the tiddler store, from where it is synchronised into the DOM. This is done to improve performance by minimising the DOM interactions during the refresh cycles.
It also determines the standard UI flow:
From a technical perspective, TiddlyWiki is a fairly classic MVC architecture, with strict separation of concerns. The model is the tiddler store, the view is a rendering tree (such as the one created from $:/core/ui/PageTemplate in startup.js), and the controller is the core code itself.
The TiddlyWiki community holds regular Google Hangouts, usually every Tuesday from 4pm to 6pm (UK time). They are announced in the TiddlyWiki Google group and on the TiddlyWiki Twitter account.
Past Hangouts are archived in this YouTube playlist:
TiddlyWiki in the Sky for TiddlyWeb allows content to be synchronised between TiddlyWiki running in the browser and a TiddlyWeb (or TiddlySpace) server. Features include:
The implementation is somewhat experimental, and includes these limitations:
To try out TiddlyWiki in the Sky for TiddlyWeb:
<myspace>tw5tiddlywebhttp://<myspace>.tiddlyspace.com/tw5This brief screencast shows how to setup Firefox for Android so you can save changes to TiddlyWiki:
node-webkit allows TiddlyWiki to be set up as a native application for Windows, Mac OS X or Linux.
index.htmlpackage.json with the following content:{ "name": "tiddlywiki", "main": "./index.html", "window": { "toolbar": true, "width": 1024, "height": 768 } }
MP3 audio and H264 video are not supported without special steps described on the node-webkit wiki.
Running TiddlyWiki on Node.js brings several important benefits over and above the single file version:
npm install -g tiddlywikiIf it fails with an error you may need to re-run the command as an administrator:
npm install -g tiddlywiki(Windows)
sudo npm install -g tiddlywiki(Mac/Linux)
tiddlywiki --version
5.0.8-beta; you may also see other debugging information reported)tiddlywiki mynewwiki --init server to create a folder for a new wiki that includes server-related componentstiddlywiki mynewwiki --server to start TiddlyWikiThe -g flag causes TiddlyWiki to be installed globally. Without it, TiddlyWiki will only be available in the directory where you installed it.
A slightly different method for installation is recommended if you plan on forking the source code in order to study it or contribute to it. See Working with the TiddlyWiki5 repository.
TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on TiddlyWikiFolders, TiddlerFiles and TiddlyWikiFiles.
For example, the following command loads the tiddlers from a TiddlyWiki HTML file and then saves one of them in static HTML:
tiddlywiki --verbose --load mywiki.html --rendertiddler ReadMe ./readme.htmlRunning tiddlywiki from the command line boots the TiddlyWiki kernel, loads the core plugins and establishes an empty wiki store. It then sequentially processes the command line arguments from left to right. The arguments are separated with spaces.
The first argument is the optional path to the TiddlyWikiFolder to be loaded. If not present, then the current directory is used.
The commands and their individual arguments follow, each command being identified by the prefix --.
tiddlywiki [<wikipath>] [--<command> [<arg>[,<arg>]]]The available commands are:
See also:
If you've installed TiddlyWiki on Node.js on the usual way, when a new version is released you can upgrade it with this command:
npm update -g tiddlywikiOn Mac or Linux you'll need to add sudo like this:
sudo npm update -g tiddlywikiTiddlyWiki5 can be used to build older 2.x.x versions of TiddlyWikiClassic from their constituent components. Doing so involves these features:
tiddlywiki/classictools plugin, containing a deserializer module which allows tiddlers to be loaded from TiddlyWiki 2.x.x .recipe filesstripcomments format for the ViewWidget, which strips single line JavaScript comments starting //#stripTitlePrefix='yes' attribute of the FieldsWidget, which removes prefixes wrapped in curly braces from the title attribute{tiddler}HelloThere would be transformed to HelloThereTiddlyWikiClassic is built from the command line by running TiddlyWiki on Node.js. A typical usage would be:
node ../../tiddlywiki.js \
--verbose \
--load <path_to_recipe_file> \
--rendertiddler $:/core/templates/tiddlywiki2.template.html <path_to_write_index_file> text/plain \
|| exit 1TiddlyWiki5 is a reboot of TiddlyWiki for the next 25 years. It is a complete interactive wiki in JavaScript that can be run in the browser or on the server under Node.js.
This information is for people who are working on the development of TiddlyWiki5 itself, and isn't relevant for end users
Installing TiddlyWiki5 with NPM downloads a snapshot release of TiddlyWIki5. To use a development copy of the TiddlyWiki5 repository instead of the copy installed by NPM, use this command within the root of the TiddlyWiki5 repo:
npm linkAs releases are made during development it is necessary to adjust the version number of the TiddlyWiki5 core. This is done with the npm version command. For example:
npm version 5.0.0-alpha.10As described in #10 in this article by npm's author, when run from within a git repo this command will also commit the change and tag it
Each release of TiddlyWiki5 is identified by a version number that complies with the Semantic Versioning 2.0.0 standard.
According to the standard:
Given a version number MAJOR.MINOR.PATCH, increment the:
MAJOR version when you make incompatible API changes,
MINOR version when you add functionality in a backwards-compatible manner, and
PATCH version when you make backwards-compatible bug fixes.
Additional labels for pre-release and build metadata are available as extensions to the MAJOR.MINOR.PATCH format.While in alpha TiddlyWiki5 uses the pre-release label "alpha", for example:
5.0.1-alphaEach new alpha or beta release will bump the PATCH version number. This breaks the strict semantics of versioning because PATCH increments are supposed to be reserved for compatible changes.
Note that prior to 5.0.1-alpha, TiddlyWiki5 used version numbers formatted as 5.0.0-alpha.19. The change was made to enable the upgrade mechanism to recognise plugin updates from the version information.
During development when a new release is being prepared, the pre-release label is set to prerelease.
Version numbers
TiddlyWiki5 uses the version information attached to plugins for determining which of two plugins is more recent during an upgrade or import. The pre-release label is ignored when performing these comparisons.
"TiddlyWiki Classic" refers to versions prior to 5.0, when TiddlyWiki was completely rewritten from the ground up. TiddlyWiki Classic is still being maintained at:
http://classic.tiddlywiki.com/
MarioPietsch has started a site comparing the syntax and other changes between TiddlyWikiClassic and TiddlyWiki version 5:
As well as traditional single file wikis, TiddlyWiki on Node.js supports wikis that are stored as a folder of individual tiddler files.
Wiki folders can contain the following files and folders:
Only the tiddlywiki.info file is required, the tiddlers and plugins folders are optional. Any files and folders not listed above are ignored.
tiddlywiki.info fileThe tiddlywiki.info file in a wiki folder contains a JSON object comprising the following fields:
Configuration options include:
For example:
{
"plugins": [
"tiddlywiki/tiddlyweb",
"tiddlywiki/filesystem"
],
"includeWikis": [
"../tw5.com"
],
"build": {
"index": [
"--rendertiddler","$:/core/save/all","index.html","text/plain"],
"favicon": [
"--savetiddler","$:/favicon.ico","favicon.ico",
"--savetiddler","$:/green_favicon.ico","static/favicon.ico"]
},
"config": {
"retain-original-tiddler-path": true
}
}tiddlers folderAll the TiddlerFiles in the tiddlers folder are read into the wiki at startup. Sub-folders are scanned recursively for TiddlerFiles.
Sub-folders within the tiddlers folder can also be given a tiddlywiki.files JSON file that overrides the default processing for that folder. The file format is illustrated with this example from the D3 plugin:
{
"tiddlers": [
{
"file": "d3.min.js",
"fields": {
"type": "application/javascript",
"title": "$:/plugins/tiddlywiki/d3/d3.js",
"module-type": "library"
},
"prefix": "var d3;if($tw.browser){\n",
"suffix": "}\nexports.d3 = d3;\n"
},
{
"file": "cloud/d3.layout.cloud.js",
"fields": {
"type": "application/javascript",
"title": "$:/plugins/tiddlywiki/d3/d3.layout.cloud.js",
"module-type": "library"
}
}
]
}The JSON data consists of an object with a tiddlers property that contains an array of information about each tiddler to be loaded into the wiki. That information consists of:
file: the relative or absolute path to the file to includefields: an object containing fields that override any provided in the tiddler fileprefix & suffix: (optional) specify strings to be prefixed and suffixed to the tiddler file text contentAs the structures within your TiddlyWiki documents get more complex it can be hard to keep the titles of tiddlers consistent. For example, should terms be defined in the plural or the singular? Camel case or separate words?
Recording a formal titling policy can help to reduce confusion. For example, the titling policies for this wiki are:
Policies that may make sense for your own wikis include:
$:/_ for any system tiddlers that you create to ensure that they are near the top of the system tiddler listing in the sidebarThe TranscludeWidget dynamically imports content from another tiddler.
| Attribute | Description |
|---|---|
| tiddler | The title of the tiddler to transclude (defaults to the current tiddler) |
| field | The field name of the current tiddler (defaults to "text"; if present takes precedence over the index attribute) |
| index | The index of a property in a DataTiddler |
| mode | Override the default parsing mode for the transcluded text to "block" or "inline" |
The TranscludeWidget treats any contained content as a fallback if the target of the transclusion is not defined (ie a missing tiddler or a missing field).
TiddlyWiki parses text in two modes:
Usually, the mode is determined by whether the transclude widget itself has been parsed in block or inline mode. This can be overridden with the mode attribute.
For example, consider tiddler "A" with this content:
# Item one
#<$transclude tiddler="B"/>
# Item twoAnd a tiddler "B" with this content:
# Item one - a
# Item one - bThe result will be something like this:
This can be fixed by amending tiddler "A":
# Item one
#<$transclude tiddler="B" mode="block"/>
# Item twoYou can incorporate the content of one tiddler within another using the transclusion notation:
{{MyTiddler}} transcludes a single tiddler{{MyTiddler||TemplateTitle}} displays the tiddler through a specified TemplateTiddler{{||TemplateTitle}} displays the specified template tiddler without altering the current tiddlerYou can also use a TextReference instead of a tiddler title:
{{MyTiddler!!field}} transcludes a specified field of a tiddler{{!!field}} transcludes a specified field of the current tiddler{{MyTiddler##index}} transcludes a specified indexed property of a DataTiddler{{##index}} transcludes a specified indexed property of the current DataTiddlerA similar syntax can be used to transclude a list of tiddlers matching a specified TiddlerFilter:
{{{ [tag[mechanism]] }}}
{{{ [tag[mechanism]] ||TemplateTitle}}}The translation mechanism of TiddlyWiki manages and switches between language plugins that provide translations of the TiddlyWiki user interface. How to create a translation for TiddlyWiki explains how translators can create and submit translations for TiddlyWiki.
The title of the current language plugin is read from the tiddler $:/language. If the selected plugin changes then any displayed translateable text automatically changes.
Translation plugins are bundles of tiddlers that each contain an indepedent translatable string. The strings are transcluded as needed.
Translatable strings are generally in the namespace $:/language/, for example:
WikiText can include blocks of text that are rendered with an explicit ContentType like this:
$$$image/svg+xml
<svg xmlns="http://www.w3.org/2000/svg" width="150" height="100">
<circle cx="100" cy="50" r="40" stroke="black" stroke-width="2" fill="green" />
</svg>
$$$This renders as:
It is also possible to abbreviate the ContentType to a file extension. For example:
$$$.svg
<svg xmlns="http://www.w3.org/2000/svg" width="150" height="100">
<circle cx="100" cy="50" r="40" stroke="black" stroke-width="2" fill="red" />
</svg>
$$$This renders as:
Unknown types render as plain text:
$$$text/unknown
Some plain text, which will not be //formatted//.
$$$Which renders as:
Some plain text, which will not be //formatted//.A render type can also be specified, causing a particular text rendering to be displayed. For example:
$$$text/vnd.tiddlywiki>text/html
This is ''some'' wikitext
$$$
$$$text/vnd.tiddlywiki>text/plain
This is ''some'' wikitext
$$$Renders as:
<p>This is <strong>some</strong> wikitext</p>
This is some wikitext
There are several methods for upgrading an existing TiddlyWiki version 5 document to a new release. There is a different procedure for upgrading TiddlyWiki on Node.js.
Regardless of which method you use, remember the The First Rule of Using TiddlyWiki:
You are responsible for looking after your own data; take care to make backups, especially when upgrading the TiddlyWiki core
This process will work on most desktop browsers. Note that none of your personal data leaves your browser with this process.
This will download a file called empty.html to your computer. This file is the upgrade of your old file. You may need to open the location where empty.html was downloaded, rename empty.html with the name of the old file you are upgrading, and replace the old file by moving the new file in its place.
For the moment you'll also need to manually update any plugins that are not included in empty.html:
- Open the control panel to the Plugins tab in your upgraded wiki
- Check the version numbers of the plugins you are using; any plugins with an older version than the version of $:/core will probably need updating
- Locate a wiki with the plugins you need to update and open the control panel Plugins tab
- http://tiddlywiki.com/d3demo.html for the D3 plugin
- http://tiddlywiki.com/codemirrordemo.html for the CodeMirror plugin
- http://tiddlywiki.com/markdowndemo.html for the MarkDown plugin
- http://tiddlywiki.com/ for most of the others
- Drag the plugin links one by one back to your own wiki. You should see the version numbers update in the control panel
- Save your wiki
You can also download http://tiddlywiki.com/empty.html locally and perform the same drag-and-drop procedure to upgrade your files.
Particularly during the beta, it is possible for a customisation applied in a previous version to break when upgraded to the latest version. Use SafeMode to investigate and fix these problems.
If you've installed TiddlyWiki on Node.js on the usual way, when a new version is released you can upgrade it with this command:
npm update -g tiddlywikiOn Mac or Linux you'll need to add sudo like this:
sudo npm update -g tiddlywikiBy default, when running TiddlyWiki on Node.js, the server exposes the wiki at the URI formed from the protocol, host and port - for example, http://127.0.0.1:8080/.
There are two steps to running the wiki at a custom path like http://127.0.0.1:8080/path/to/my/wiki/:
/path/to/my/wiki as the pathprefix argument of the ServerCommand$protocol$//$host$/path/to/my/wiki/The usual way of modifying the appearance of a TiddlyWiki is to use one of the available themes, or to modify the colour palette.
You can also use custom CSS stylesheets by tagging tiddlers with $:/tags/stylesheet. For example, create a tiddler with the tag $:/tags/stylesheet and the following content in order to change the page background colour to red:
html body.tw-body {
background: red;
}Note that custom stylesheets are applied independently to the theme stylesheets. This means that it is frequently necessary to use CSS specificity to reliably override settings within the theme. This means ensuring that the CSS rule in your custom stylesheet is more specific than the theme rule that you are overriding. "More specific" generally means using more CSS rules. So, html body.tw-body is more specific than body.tw-body.
Usually it is best to use the type text/css for stylesheets. This treats them as plain stylesheets, and ensures that TiddlyWiki doesn't apply any wiki processing to them.
If you wish to use macros and transclusions in your stylesheets you should instead use the default WikiText type text/vnd.tiddlywiki. This allows full WikiText processing to be performed. Here is an example:
\rules only filteredtranscludeinline transcludeinline macrodef macrocallinline
body.tw-body pre {
<<box-shadow "inset 0 1px 0 #fff">>
}The \rules pragma at the top of the tiddler restricts the WikiText to just allow macros and transclusion. This avoids mistakenly triggering unwanted WikiText processing.
Several globally available macros are provided that are helpful in constructing stylesheets. See $:/core/ui/PageStylesheet for the definitions of these macros.
<<colour name>> and <<color name>> retrieve named colours from the current colour palette<<box-shadow shadow>> specify a box-shadow<<filter filter>> specify a CSS filter<<transition transition>> specify a CSS transition<<transform-origin origin>> specify the CSS transform origin<<background-linear-gradient gradient>> specify a linear gradient<<datauri title>> retrieves the base64 content of a tiddler for use via the CSS url() operatorTiddlyWiki5 can be used to produce documentation for GitHub projects. It lets you maintain a single set of documentation as a TiddlyWikiFolder containing separate tiddler files under source code control, and then use it to produce readme.md files for inclusion in project folders, or HTML files for storage in GitHub Pages. Both features are demonstrated by TiddlyWiki5 itself.
readme.md filesWhen displaying the contents of a folder GitHub will look for a readme.md file and display it. Note that it will not display full HTML files in this way, just static MarkDown files (this is a security measure). Happily MarkDown permits a safe subset of HTML, and thus to generate a readme.md file that is suitable for GitHub it is just necessary for TiddlyWiki5 to generate the content of the <body> element of an HTML document, and give it the appropriate filename.
This is done in bld.sh by this command:
--rendertiddler ReadMe ./readme.md text/htmlIt saves the tiddler ReadMe to the file ./readme.md in the text/html format.
By default, tiddler links will be rendered as <a> links to a relative URI consisting of the title of the tiddler. This behaviour can be overridden by defining the macro tw-wikilink-template, as is done at the top of the tiddler ReadMe:
\define tw-wikilink-template() http://tiddlywiki.com/static/$uri_doubleencoded$.htmlSee the LinkWidget for more details.
In this example, tiddler links are rendered as links to the static rendering of tw5.com.
Publishing to GitHub Pages is very straightforward. In the case of TiddlyWiki5, several different build products are published.
The bld.sh script deposits the build products directly into the local clone of the repo associated with the GitHub Pages account. There is then a manual step to review changes and push them up to github.com.
TiddlyWiki5 can be used on the command line to perform an extensive set of operations based on TiddlyWikiFolders, TiddlerFiles and TiddlyWikiFiles.
For example, the following command loads the tiddlers from a TiddlyWiki HTML file and then saves one of them in static HTML:
tiddlywiki --verbose --load mywiki.html --rendertiddler ReadMe ./readme.htmlRunning tiddlywiki from the command line boots the TiddlyWiki kernel, loads the core plugins and establishes an empty wiki store. It then sequentially processes the command line arguments from left to right. The arguments are separated with spaces.
The first argument is the optional path to the TiddlyWikiFolder to be loaded. If not present, then the current directory is used.
The commands and their individual arguments follow, each command being identified by the prefix --.
tiddlywiki [<wikipath>] [--<command> [<arg>[,<arg>]]]The available commands are:
See also:
TiddlyDesktop is an app for Windows, Mac OS X and Linux that lets you work with TiddlyWiki files.
See the Introducing TiddlyDesktop Video
TiddlyWiki5 allows you to use SVG to display vector graphics in two ways:
image/svg+xml are interpreted as SVG images, and displayed and transcluded as self-contained <img> elements with the SVG embedded as a data URI in the src attribute.You can embed an SVG image tiddler using the ordinary transclusion syntax:
{{Motovun Jack.jpg}}You can also use TypedBlockWikiText to embed an inline SVG tiddler.
The implications of the image being rendered within an <img> element are that it is sandboxed; it can't use CSS styles from the parent document, for example. Neither can the image use WikiText features like transclusion.
The other way to use SVG is to embed the <svg> element directly. For example:
Note that inline SVG elements don't need an <?xml version="1.0"?> directive.
You can include simple text strings in SVG images using the <text> element:
HTML or WikiText content can be included within inline SVG images using the <foreignObject> element. For example:
When embedding SVG elements you can also use WikiText features like transclusion. For example, here is an SVG circle with the radius set to the value in the tiddler $:/SVGExampleRadius:
You can edit the value of the radius here:
The version macro returns the current TiddlyWiki version number.
The version macro takes no parameters:
Version number: <<version>>Version number: 5.0.13-beta
The aim is to curate a series of videos to guide people through getting up and running with TiddlyWiki. Contributions are welcome.
This brief tutorial takes you through the basics of saving changes with a standalone TiddlyWiki5 file.
This brief screencast shows how to setup Firefox for Android so you can save changes to TiddlyWiki:
This brief introduction shows how to install and use TiddlyDesktop:
This video of the second OXTWIG meeting starts with a tutorial overview demonstrating how to use TiddlyWiki in different scenarios:
The view widget displays the contents of a tiddler field in a specified format.
The content of the <$view> widget is displayed if the field or property is missing or empty.
| Attribute | Description |
|---|---|
| tiddler | The title of the tiddler (defaults to the WidgetVariable: currentTiddler) |
| field | The name of the field to view (defaults to "text") |
| index | The name of the index to view |
| format | The format for displaying the field (see below) |
| template | The optional template used with certain formats |
The following formats can be specified in the format attribute:
| Format | Description |
|---|---|
| text | Plain text |
| htmlwikified | The field is wikified and the resulting HTML returned as plain text |
| htmlencoded | The field is displayed with HTML encoding issues |
| date | The field is interpreted as a UTC date and displayed according to the DateFormat specified in the template attribute |
| relativedate | The field is interpreted as a UTC date and displayed as the interval from the present instant |
| stripcomments | The field is interpreted as JavaScript source code and any lines beginning \\# are stripped |
| jsencoded | The field is displayed as a JavaScript encoded string |
The tw-cancel-tiddler message abandons the changes in a draft tiddler. It requires the following properties on the event object:
| Name | Description |
|---|---|
| param | Title of the tiddler that is being cancelled out of edit mode |
| tiddlerTitle | Fallback title that is used if param isn't specified (automatically set by the ButtonWidget) |
The cancel tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.
The tw-clear-password message clears the current password from the password vault, clearing the $:/isEncrypted tiddler. See EncryptionMechanism for details.
This message is typically generated with the ButtonWidget, and is handled by the core itself.
The close all tiddlers message empties the story list.
The close all tiddlers message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.
The tw-close-other-tiddlers message removes all but a specified tiddler from the story list. It requires the following properties on the event object:
| Name | Description |
|---|---|
| param | Title of the tiddler that is not to be closed |
| tiddlerTitle | Fallback title that is used if param isn't specified (automatically set by the ButtonWidget) |
The close other tiddlers message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.
The tw-close-tiddler message removes a specified tiddler from the story list. It requires the following properties on the event object:
| Name | Description |
|---|---|
| param | Title of the tiddler that is to be closed |
| tiddlerTitle | Fallback title that is used if param isn't specified (automatically set by the ButtonWidget) |
The close tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.
The tw-delete-tiddler message deletes the specified tiddler and removes it from the current story. If the tiddler is a draft then it also deletes the tiddler specified in the draft.of field. The delete tiddler message requires the following properties on the event object:
| Name | Description |
|---|---|
| param | Title of the tiddler that is to be deleted |
| tiddlerTitle | Fallback title that is used if param isn't specified (automatically set by the ButtonWidget) |
The delete tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.
The tw-edit-tiddler message replaces the specified tiddler in the current story with a draft version of itself. It requires the following properties on the event object:
| Name | Description |
|---|---|
| param | Title of the tiddler that is being switched to edit mode |
| tiddlerTitle | Fallback title that is used if param isn't specified (automatically set by the ButtonWidget) |
The edit tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.
The tw-home message resets the story list to the tiddlers defined in $:/DefaultTiddlers. It does not require any properties on the event object.
The cancel tiddler message is usually generated with the ButtonWidget and is handled by the core.
The tw-import-tiddlers message inserts a list of tiddlers into the store. If multiple tiddlers are imported then a report is displayed; if only one tiddler is imported then it is displayed instead. The import message requires the following properties on the event object:
| Name | Description |
|---|---|
| param | JSON text of the array of tiddlers to be imported |
This message is handled by the NavigatorWidget.
The import tiddlers message is usually generated with the DropzoneWidget or the BrowseWidget, and is handled by the NavigatorWidget.
The tw-navigate message inserts the specified tiddler into the story and puts it at the top of the history stack. If the tiddler is not already present in the story then it will be positioned immediately after the tiddler specified in event.navigateFromTitle.
The navigate message requires the following properties on the event object:
| Name | Description |
|---|---|
| navigateTo | Title of the tiddler that is being navigated |
| navigateFromTitle | Title of the tiddler from which the navigation was initiated |
| navigateFromClientRect | Bounding rectangle in client page coordinates of the element initiating the navigation |
| navigateSuppressNavigation | true causes the new tiddler to only be added to the story, and not the history stack. This suppresses the scrolling associated with navigating to a tiddler |
The navigate message can be generated by the LinkWidget and the ButtonWidget, and is handled by the NavigatorWidget.
The new tiddler message creates a new draft tiddler and adds it to the current story. It requires the following properties on the event object:
| Name | Description |
|---|---|
| param | Optional title of a tiddler to use as a template for the new tiddler |
| navigateFromTitle | Title of the tiddler from which the navigation to the new tiddler was initiated |
The new tiddler message is usually generated with the LinkWidget or the ButtonWidget and is handled by the NavigatorWidget.
The tw-save-tiddler message is applied to draft tiddlers. It saves the draft over the tiddler identified in the draft.of field and then deletes the draft. The save tiddler message requires the following properties on the event object:
| Name | Description |
|---|---|
| param | Title of the tiddler that is being switched out of edit mode |
| tiddlerTitle | Fallback title that is used if param isn't specified (automatically set by the ButtonWidget) |
The save tiddler message is usually generated with the ButtonWidget and is handled by the NavigatorWidget.
The tw-set-password message prompts the user for a new password and stores it in the password vault, replacing any existing password. It also sets the $:/isEncrypted tiddler. See EncryptionMechanism for details.
This message is typically generated with the ButtonWidget, and is handled by the core itself.
Widget messages are generated by widgets in response to user actions. They flow up the widget tree until they are handled by an ancestor widget.
The following widget messages are implemented by the core:
Widget modules are used as part of the RenderingMechanism to implement each type of renderable entity. As well as the widgets that are familiar to end users, the following primitives are also implemented as widgets:
All widgets inherit from a base widget class that is defined in $:/core/modules/widgets/widget.js.
The following widget properties are defined by the core. The lifecycle of a widget object is largely a matter of maintaining the consistency of these internal properties in the face of external state changes. Individual widgets usually add their own additional properties too.
| Name | Description |
|---|---|
| parseTreeNode | Reference to the parse tree node corresponding to this widget |
| wiki | Reference to the Wiki object associated with this widget |
| variables | Hashmap of information about each widget variable (see below) |
| parentWidget | Reference to the parent widget |
| document | Reference to the document object associated with this widget. Usually either the browser global document variable or a reference to the FakeDomMechanism's $tw.fakeDocument |
| attributes | Hashmap of information about each attribute attached to this widget (see below) |
| children | Array of child widgets |
| domNodes | For widgets that directly generate DOM nodes, an array of the generated nodes |
| eventListeners | Array of event listener definitions |
The widget variables defined on a widget are stored in a hashmap of the variable name. The hashmap contains:
name: name of variableparams: array of parameters for macro definitions, each {name: "<name>", default: "<optionaldefault>"}value: string value of variableThe widget attributes associated with a widget are stored in a hashmap of the attribute name. The hashmap contains an object that describes the attribute value. Currently three attribute value types are supported:
{type: "string", value: "<value>"}{type: "indirect", textReference: "<textref>"}{type: "macro", value: {name: "<macroname>", params: [{name: "<paramname>", value: "<paramvalue>"}, ... ]}The event listeners attached to a widget are stored as a hashmap by event type. Each value is a handler function that accepts a single event parameter.
The individual methods defined by the widget object are documented in the source code of $:/core/modules/widgets/widget.js. Here we give an overview of the overall lifecycle, and how the methods fit together
initialise methodwidgetClasses methodrender methodexecute methodgetVariable methodsubstituteVariableParameters methodsubstituteVariableReferences methodevaluateMacroModule methodsetVariable methodhasVariable methodgetStateQualifier methodcomputeAttributes methodhasAttribute methodgetAttribute methodassignAttributes methodmakeChildWidgets methodmakeChildWidget methodrenderChildren methodaddEventListeners methodaddEventListener methoddispatchEvent methodrefresh methodrefreshSelf methodrefreshChildren methodfindNextSiblingDomNode methodfindFirstDomNode methodremoveChildDomNodes methodWidgets provide rich functionality within WikiText. They have the same syntax as HTML elements, but the tag name always starts with $. For example:
<$button message="tw-close-tiddler">Close Me!</$button>Note that widgets inherit all the features of HTML in WikiText:
attr=<<myMacro>>)attr={{MyTiddler!!field}})See HTML in WikiText for more details.
The available widgets include:
WikiRuleModules cover the module types wikirunrule, wikiblockrule and wikipragmarule. Modules of these types encapsulate the logic of individual parsing rules used by the WikiParser engine. For example, there is a wikirunrule module that identifies references to HTML entities by matching the pattern &<chars>;.
Pragma rules are applied at the start of a block of text, and cover definitions and declarations that affect the parsing of the rest of the text. Block rules are only applied at the beginning of a block of wikitext, while run rules can appear anywhere. The only current example of a pragma rule is for macro definitions.
Examples of block rules:
Examples of run rules:
Parser rule modules extend the $tw.WikiParserRule class. This is done by instantiating the class and then copying the exports of the rule module onto the instance. In this way, the parser rule can override the base behaviour of the $tw.WikiParserRule class. In particular, the base class incorporates logic for using regular expressions to match parse rules but this logic could be overridden by a parse rule that wanted to, say, use indexOf() instead of regular expressions.
The standard methods and properties of parser rules are as follows:
name: a string containing the name of this parse ruleinit(parser): initialisation function called immediately after the constructor with a pointer back to the parser containing this rulefindNextMatch(pos): returns the position of the next match after the specified positionparse(): parses the most recent match, returning an array of the generated parse tree nodes. Pragma rules don't return parse tree nodes but instead modify the parser object directly (for example, to add local macro definitions)The built in parser rules use regular expression matching. Such rules can take advantage of the implementation of findNextMatch() in the base $tw.WikiRule class by ensuring that their init() method creates a matchRegExp property containing the regular expression to match. The match property contains the details of the match for use in the parse() method.
WikiText is a concise, expressive way of typing a wide range of text formatting, hypertext and interactive features. It allows you to focus on writing without a complex user interface getting in the way. It is designed to be familiar for users of MarkDown, but with more of a focus on linking and the interactive features.
Under Windows it is possible to convert TiddlyWiki into a true local application by renaming the HTML file to have the extension *.hta. The fsosaver module can then use the ActiveX FileSystemObject to save changes.
Note that one disadvantage of this approach is that the TiddlyWiki file is saved in UTF-16 format, making it up to twice as large as it would be with the usual UTF-8 encoding. However, opening and saving the file via another saving method will re-encode the file to UTF-8.
See Wikipedia for more details: http://en.wikipedia.org/wiki/HTML_Application
If you plan on working with the TiddlyWiki5 source code then follow these steps:
npm link (Windows) or sudo npm link (Mac/Linux) to tell npm to use this copy of the repo as the globally installed oneAfter this procedure you can work with TiddlyWiki5 via npm as though it were installed in the usual way with npm install -g tiddlywiki.
See also Scripts for TiddlyWiki on Node.js.